ShellGuard TOTP v0.0.3.0

🦞 ShellGuard TOTP — Release v0.0.3.0 (Build 17)

Phase 13 & 13.5: Advanced Import/Export, Migration Polish, Google Authenticator Multi-QR & OWASP Step-Up Auth: versionCode 17 (versionName = "0.0.3.0"). Delivers a unified multi-vault ingestion engine (Bitwarden Vault, Bitwarden Auth, Aegis, 2FAS) with zero-knowledge volatile RAM sanitization, Google Authenticator 10-token QR migration export carousels via pure Kotlin protobuf and ZXing, hardware-backed step-up authentication under OWASP MASVS-AUTH-1 (BiometricPrompt + Master PIN/Password fallback challenge dialog) with dynamic FLAG_SECURE window protection, offline-first YAGNI sync (PENDING_SYNC), native SQLCipher 16 KB debug symbol tables (ndk.debugSymbolLevel = "SYMBOL_TABLE"), and 100% SSoT documentation synchronization. Install over previous builds in place; vault data is preserved.

Phase 13 & 13.5: Advanced Import/Export, Google Authenticator Multi-QR & OWASP MASVS-AUTH-1 Step-Up Security

███████╗██╗   ██╗███████╗██╗     ██╗              ██████╗   ██╗   ██╗   █████╗    ██████╗     ██████╗ 
██╔════╝██║   ██║██╔════╝██║     ██║              ██╔═══╝   ██║   ██║  ██╔══██╗  ██╔══██╗    ██╔══██╗
███████╗███████║█████╗   ██║     ██║              ██║ ███╗  ██║   ██║  ███████║  ██████╔╝    ██║   ██║
╚════██║██╔══██║██╔══╝   ██║     ██║              ██║   ██║  ██║   ██║  ██╔══██║  ██╔══██╗    ██║   ██║
███████║██║   ██║███████╗███████╗  ╚██████╔╝╚██████╝  ██║   ██║  ██║   ██║   ██████╔╝
╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝    ╚═╝   ╚═╝   ╚═╝   ╚═╝   ╚═╝   ╚═╝
                                                  ~ **ClawStack Mobile Studios©™** ~

---

🚀 The Core Summary

Welcome to v0.0.3.0 of ShellGuard-TOTP — Phase 13 & 13.5: Advanced Import/Export, Migration Polish & OWASP Step-Up Auth (Build 17). This milestone implements Tasks 25, 25b, 26, and 26.5, expanding ShellGuard-TOTP's interoperability footprint to support frictionless migration from major industry authenticators while reinforcing our zero-knowledge boundary defense.

Users can now seamlessly migrate accounts from Bitwarden (Vault & Authenticator JSON), Aegis, and 2FAS backups with zero credential leakage—foreign passwords and personal notes are purged in volatile RAM before ever reaching disk. Vaults can also be exported to Google Authenticator using pure Kotlin protobuf varint serialization, rendering interactive 10-token QR code carousels via ZXing. Under OWASP MASVS-AUTH-1, sensitive export surfaces are fortified with mandatory step-up authentication across all device configurations (BiometricPrompt when available, falling back to a Master PIN/Password challenge dialog when biometrics are absent or disabled), wrapped in dynamic FLAG_SECURE window protections.

---

💎 Key Themes & Highlights

📥 1. Unified Multi-Format Intake Engine & Volatile RAM Sanitizer (Task 25)

• Multi-Format Ingestion: MultiFormatMigrationEngine normalizes incoming backups from Bitwarden Vault JSON, Bitwarden Authenticator JSON, Aegis JSON, and 2FAS JSON into standard ParsedTotpItem models.
• Zero-Knowledge RAM Sanitization: Strips passwords, secure notes, card data, and non-2FA metadata in volatile RAM, guaranteeing 0% credential leakage into local persistence.
• Dual Vault Persister: MigrationPersister provides selectable conflict resolution policies: SKIP_DUPLICATES (fingerprint deduplication), OVERWRITE_EXISTING, and KEEP_BOTH.

🔄 2. Google Authenticator Multi-QR Migration Carousel (Tasks 25 & 26)

• Pure Kotlin Protobuf Serialization: GoogleAuthMigrationEncoder implements Google Authenticator otpauth-migration://offline?data=... payload encoding using varint wire formats with zero heavy protoc runtime dependencies.
• 10-Token Chunking: Automatically partitions large vaults into manageable 10-token batches for optimal camera scannability.
• ZXing Barcode Rendering: High-contrast, scannable 2D QR bitmaps wrapped in padded white containers for instant optical recognition.

🔒 3. OWASP MASVS-AUTH-1 Step-Up Authentication & Privacy Shield (Task 26.5)

• Mandatory Step-Up Challenge: Exporting plaintext secrets or viewing migration QR carousels strictly enforces step-up verification.
• Biometric + PIN Fallback Pairing: Challenges AndroidX BiometricPrompt when biometric hardware is enrolled and enabled; strictly falls back to a Master PIN / Password challenge AlertDialog validating against authViewModel.unlockWithSecret() when biometrics are unavailable or disabled in settings. Never fails open.
• Dynamic FLAG_SECURE Window Shield: GoogleAuthExportViewerDialog and step-up challenge dialogs enforce FLAG_SECURE, preventing screenshots or thumbnail leakage in the Android Recents menu.

⚡ 4. Offline-First YAGNI Sync & Summary Audit Logging (Task 26.5)

• Offline-First Data Flow: Bulk imports insert records directly into local SQLCipher Room storage with syncState = PENDING_SYNC. Network replication is delegated asynchronously to TotpSyncWorker, eliminating UI thread blocking and network failure vulnerabilities.
• Compact Audit Log: Consolidates mass import operations into a single structured summary row in AuditLogEntity, preventing database bloat during 200+ account migrations.

📦 5. Native Debug Symbol Tables & Packaging (Task 25b)

• Play Console Symbol Resolution: Configured ndk { debugSymbolLevel = "SYMBOL_TABLE" } in app/build.gradle.kts to package libsqlcipher.so native debug symbol tables directly inside release App Bundles (.aab).
• 16 KB Memory Page-Size Compliance: Native binaries fully aligned to 16 KB segment boundaries for Android 15+ (API 35/36).

---

🧪 Verification Record

• 107 unit and Robolectric tests passing 100% green (./gradlew testDebugUnitTest).
• Clean build compilation: ./gradlew assembleDebug succeeded.
• Deterministic doc audit: scripts/audit_docs_drift.py returned 0 (100% compliance).
• Cloud CI Verification Gate: Verified in GitHub Actions runner 39015197453 (ubuntu-latest).
• Packaging invariants: targetSdk = 36, sqlcipher 4.6.1 (16 KB page-aligned), jniLibs.useLegacyPackaging = false, dynamic theming with LocalShellGuardColors.

---

🛡️ Security Posture — Hardened

Android KeyStore StrongBox keys, SQLCipher AES-256 at rest (Room Database v2), OWASP MASVS-AUTH-1 step-up authentication with Master PIN fallback dialog, emergency panic wipe broadcast receiver, append-only security audit trail, dynamic FLAG_SECURE window shields, zero-knowledge volatile RAM sanitization, offline-first background synchronization, Android 16 (API 36) + 16 KB page-size kernel ready.

---

ClawStack Mobile Studios©™ — Build features around security, not security around features.

ShellGuard TOTP v0.0.2.3

🦞 ShellGuard TOTP — Release v0.0.2.3 (Build 16)

Phase 12: Security Suite, Panic Purge, Audit Logging & Web Server v0.0.2.3 Sync Parity: versionCode 16 (versionName = "0.0.2.3"). Delivers advanced vault security controls (tap-to-reveal tokens, screen security toggle, emergency panic purge trigger integration), a local append-only security Audit Log recording cryptographic and access events, and complete protocol re-alignment with ShellGuard Web Server v0.0.2.3 (Build 25) restoring dynamic TOTP URI parsing during remote synchronization. Install over previous builds in place; vault data is preserved.

Phase 12: Security Suite, Panic Purge, Security Audit Logging & Web Server v0.0.2.3 Sync Parity

███████╗██╗   ██╗███████╗██╗     ██╗              ██████╗   ██╗   ██╗   █████╗    ██████╗     ██████╗ 
██╔════╝██║   ██║██╔════╝██║     ██║              ██╔═══╝   ██║   ██║  ██╔══██╗  ██╔══██╗    ██╔══██╗
███████╗███████║█████╗   ██║     ██║              ██║ ███╗  ██║   ██║  ███████║  ██████╔╝    ██║   ██║
╚════██║██╔══██║██╔══╝   ██║     ██║              ██║   ██║  ██║   ██║  ██╔══██║  ██╔══██╗    ██║   ██║
███████║██║   ██║███████╗███████╗  ╚██████╔╝╚██████╝  ██║   ██║  ██║   ██║   ██████╔╝
╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝    ╚═╝   ╚═╝   ╚═╝   ╚═╝   ╚═╝   ╚═╝
                                                  ~ **ClawStack Mobile Studios©™** ~

---

🚀 The Core Summary

Welcome to v0.0.2.3 of ShellGuard-TOTP — Phase 12: Security Suite, Panic Purge, Audit Logging & Web Server v0.0.2.3 Sync Parity (Build 16). This major release implements Tasks 23, 24, and 24b, establishing deep system security enhancements and repairing the remote synchronization bridge with the updated ShellGuard Web Server v0.0.2.3 (Build 25).

Vaults gain granular defense controls including configurable Tap-to-Reveal timeouts, dynamic FLAG_SECURE window management with user-facing risk disclosures, an emergency broadcast panic wipe receiver, and an append-only Room-backed security audit log. Concurrently, the remote sync intake pipeline has been upgraded with TotpUriParser to dynamically ingest RFC 6238 Key URIs carrying custom hash algorithms (SHA256/512), 8 digits, and custom intervals. Pre-flight verification passed 100% green across all 107 automated unit and Robolectric tests, verified live on both phone (Google Pixel) and tablet (Nexus 7) form factors.

---

💎 Key Themes & Highlights

🛡️ 1. Security Suite & Granular Privacy Controls (Tasks 23 & 24)

• SecurityPreferenceController: Encrypted SharedPreferences management for device-level security options (allowScreenshots, tap-to-reveal timeout duration, panic purge enabled).
• Dynamic FLAG_SECURE Protection: MainActivity reactively toggles window anti-snoop protection. Screen capture prevention is strictly enforced when the vault is locked or backgrounded regardless of setting, while allowing users an opt-in toggle with an explicit risk confirmation dialog when unlocked.
• Tap-to-Reveal Timeout Selector: Configure sensitive token visibility duration (10s, 30s, 60s) with automatic re-masking.

🚨 2. Emergency Panic Purge (PanicTriggerReceiver) (Task 23)

• Broadcast-Triggered Self-Destruction: Registered ACTION_PANIC_WIPE receiver listening for emergency device broadcasts.
• Complete Sanitization: Atomically destroys Android KeyStore hardware wrapper keys, purges the EncryptedDeviceVault, drops Room database tables, and clears all cached preferences within milliseconds.

📈 3. Room-Backed Security Audit Trail (Tasks 23 & 24)

• Append-Only Event Store: Upgraded ShellGuardTotpDatabase to schema version 2 with AuditLogEntity and AuditLogDao.
• Reactive Timeline: Live tracking of key cryptographic operations: vault unlocked, biometric pass/fail, backup exported/restored, and manual/QR secret additions.
• Sub-Screen Experience: SettingsAuditLogScreen.kt provides real-time search filtering, formatted timestamps, status chips, export share intents, and clear log dialogs.

🔄 4. Web Server v0.0.2.3 Dynamic TOTP Sync Parity (Task 24b)

• Dynamic Key URI Parsing: Decrypted seeds from Web Server v0.0.2.3 are parsed via TotpUriParser.parse(), seamlessly normalizing raw Base32 keys as well as otpauth://totp/... URIs. Dynamic parameters—including HMAC-SHA256, 8-digit codes, and 60-second time steps—are preserved without Base32 decoding errors.
• Delta Fast-Filter: Added isContentIdentical() fast-filter in TotpRepository.syncRemoteVault comparing candidate entity fields before running Room write transactions, eliminating database churn on server responses with null updated_at.

---

🧪 Verification Record

• 107 unit and Robolectric tests passing 100% green (./gradlew testDebugUnitTest).
• Clean build verification: ./gradlew assembleDebug succeeded.
• Pre-flight invariants: targetSdk = 36, sqlcipher 4.6.1 (16 KB-aligned ELF segments), jniLibs.useLegacyPackaging = false, dynamic theming with LocalShellGuardColors.
• Physical Device Walkthrough (ADB TLS):
  • Google Pixel (Phone, 1080x1920): Verified PIN unlock, Settings navigation, Security sub-screen, and real-time audit logging.
  • Nexus 7 (Tablet, 1200x1920): Verified first-run vault hatching, PIN unlock, and widescreen Settings layout fidelity.

---

🛡️ Security Posture — Hardened

Android KeyStore hardware backing, SQLCipher AES-256 at rest (Database v2), emergency panic purge broadcast, Room security audit logging, dynamic FLAG_SECURE window shield, zero-knowledge sync transport, Android 16 (API 36) + 16 KB page-size kernel ready.

---

ClawStack Mobile Studios©™ — Build features around security, not security around features.

ShellGuard TOTP v0.0.2.2

🦞 ShellGuard TOTP — Release v0.0.2.2 (Build 15)

Hotfix: Compose Secret Key Masking & IME Hardening (CWE-359): versionCode 15 (versionName = "0.0.2.2"). Eliminates plaintext 2FA seed exposure in manual entry by masking the Base32 Secret Key with PasswordVisualTransformation, pairing it with an interactive eye visibility toggle, and disabling soft keyboard predictive dictionary learning. Install over previous builds in place; vault data is preserved.

Post-Hoc Interlude D: Compose Secret Key Masking & IME Hardening

███████╗██╗   ██╗███████╗██╗     ██╗              ██████╗   ██╗   ██╗   █████╗    ██████╗     ██████╗ 
██╔════╝██║   ██║██╔════╝██║     ██║              ██╔═══╝   ██║   ██║  ██╔══██╗  ██╔══██╗    ██╔══██╗
███████╗███████║█████╗   ██║     ██║              ██║ ███╗  ██║   ██║  ███████║  ██████╔╝    ██║   ██║
╚════██║██╔══██║██╔══╝   ██║     ██║              ██║   ██║  ██║   ██║  ██╔══██║  ██╔══██╗    ██║   ██║
███████║██║   ██║███████╗███████╗  ╚██████╔╝╚██████╝  ██║   ██║  ██║   ██║   ██████╔╝
╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝    ╚═╝   ╚═╝   ╚═╝   ╚═╝   ╚═╝   ╚═╝
                                                  ~ **ClawStack Mobile Studios©™** ~

---

🚀 The Core Summary

Welcome to v0.0.2.2 of ShellGuard-TOTP — Hotfix: Compose Secret Key Masking & IME Hardening (Build 15). This patch delivers critical on-device cryptographic protection for manual 2FA entry (AddSecretScreen.kt): eliminating cleartext seed exposure, enforcing non-dictionary keyboard input policies to defeat soft-keyboard word-caching (CWE-359), and providing an accessible interactive eye toggle alongside the Base32 validity indicator. All existing Settings Hub, Server & Sync, and One-Way Mirror capabilities from v0.0.2.1 remain intact. 100% test gate passing, verified live on a physical Google Pixel device.

---

💎 Key Themes & Highlights

🛡️ 1. Secret Key Masking & Anti-Snoop Protection (CWE-359)

• PasswordVisualTransformation: Manual Base32 secret input is masked by default with password bullet glyphs (••••••••), preventing shoulder-surfing, screen recording leaks, and recents thumbnail snooping.
• Predictive Dictionary Immunity: Configured KeyboardOptions(keyboardType = KeyboardType.Password, autoCorrectEnabled = false). This explicitly signals system keyboards (GBoard, SwiftKey, Samsung Keyboard, etc.) to disable personalized word suggestions, learning dictionaries, and telemetry caching for secret seed values.

👁️ 2. Interactive Visibility Toggle

• Compound Trailing Controls: Paired the Base32 input field with an interactive eye icon button (toggle_secret_visibility) displaying Icons.Default.Visibility / VisibilityOff alongside the real-time Base32 validity indicator (CheckCircle / ErrorOutline).
• Accessible Verification: Users can toggle between masked and plain text to audit character accuracy when typing complex 16–32 character RFC 6238 Base32 keys.

🎨 3. UI Modernization & Asset Parity

• Icon Modernization: Upgraded deprecated Icons.Default.ArrowBack to Icons.AutoMirrored.Filled.ArrowBack.
• README 3×3 Showcase Grid: Expanded device screenshot showcase to 9 native 1080×1920 Google Pixel captures, including the new dark-mode manual entry screen (screenshot-09-add-secret.png).

---

🧪 Verification Record

• 101+ unit and Robolectric tests passing 100% green (Phase4ScreensTest, OneWaySyncAndReadOnlyProtectionTest, DeltaSyncClassificationTest, UserPreferencesStoreTest, etc.).
• Pre-flight invariants: targetSdk = 36, sqlcipher 4.6.1 (16 KB-aligned ELF segments), jniLibs.useLegacyPackaging = false, FLAG_SECURE on release builds, cleartext restricted to LAN/VPN origins.
• Physical Google Pixel Walkthrough (ADB TLS): Verified masked password rendering, keyboard prediction suppression, eye toggle reveal/mask interaction, and live secret submission on Android 15.

---

🛡️ Security Posture — Unchanged

Android KeyStore hardware backing, SQLCipher AES-256 at rest, FLAG_SECURE screen-capture protection on release builds, zero-knowledge sync transport, Android 16 (API 36) + 16 KB page-size kernel ready.

---

ClawStack Mobile Studios©™ — Build features around security, not security around features.

ShellGuard TOTP v0.0.2.1

🦞 ShellGuard TOTP — Release v0.0.2.1 (Build 12)

Build 12 re-upload: versionCode 12 (versionName unchanged). Fixes the light-mode (Ocean Mist) typography regression found during on-device testing — text style colors are now resolved from the active theme palette instead of hard-coded dark tokens. Install over the previous build in place; vault data is preserved.

Phase 11.5: Settings Continuity — Server & Sync, Import/Export & Theme Parity

███████╗██╗   ██╗███████╗██╗     ██╗              ██████╗   ██╗   ██╗   █████╗    ██████╗     ██████╗
██╔════╝██║   ██║██╔════╝██║     ██║              ██╔═══╝   ██║   ██║  ██╔══██╗  ██╔══██╗    ██╔══██╗
███████╗███████║█████╗   ██║     ██║              ██║ ███╗  ██║   ██║  ███████║  ██████╔╝    ██║   ██║
╚════██║██╔══██║██╔══╝   ██║     ██║              ██║   ██║  ██║   ██║  ██╔══██║  ██╔══██╗    ██║   ██║
███████║██║   ██║███████╗███████╗  ╚██████╔╝╚██████╝  ██║   ██║  ██║   ██║   ██████╔╝
╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝    ╚═╝   ╚═╝   ╚═╝   ╚═╝   ╚═╝   ╚═╝
                                                  ~ **ClawStack Mobile Studios©™** ~

---

🚀 The Core Summary

Welcome to v0.0.2.1 of ShellGuard-TOTP — Phase 11.5: Settings Continuity. This is a parity-restoration release: the vault capabilities that v0.0.1.3's monolithic settings page hosted — server connection & sync, encrypted backup import/export, and theme mode + accent selection — now have first-class, semantic homes inside the v0.0.2.0 Categorized Settings Hub. The hub's ☁️ Server & Sync and 🛠️ Import & Export cards finally lead somewhere real. 101/101 tests green, verified live on device.

---

💎 Key Themes & Highlights

☁️ 1. Server & Sync Sub-screen (Task 22c)

• New ☁️ hub category hosting the full server story: live connection status, manual Sync Now, Connect → Gateway navigation, and Disconnect Vault with a confirmation dialog.
• Spotlight Tour continuity: the tourStep == 2 cutout spotlighting settings_connect_button migrated from the deleted legacy screen — onboarding points at the new home.
• Legacy SettingsScreen.kt deleted along with its route; the hub is now the single source of settings navigation.

🛠️ 2. Import & Export Sub-screen (Task 22d)

• Export: SAF CreateDocument flow producing an encrypted .sgtotp.bak backup, tagged export_backup_button.
• Restore: SAF OpenDocument flow to bring a vault back from a backup file, tagged import_backup_button.
• Secret/key resolution stays ViewModel-first — AuthViewModel.exportVaultBackup/importVaultBackup wrap the vault layer; the UI never touches key material.

🎨 3. Appearance Theme Parity (Tasks 22b/22c)

• Theme mode tiles (Dark/Light/System) and the 6 ThemeAccent palettes live in the Appearance section via the shared SettingsControls.kt tiles.
• Backed by the already-shipped themeMode/themeAccent StateFlows with persistence across cold restarts (verified by the existing AuthVaultModeRepositoryTest suite).

🔧 4. Polish & Fixes

• CRITICAL — Light-mode typography: ShellGuardTypography had hard-coded dark-mode text colors (white TextPearl, TextMuted, ClawCyan) baked into every style — white-on-white text across the app in Ocean Mist mode. Typography is now a theme-aware factory (shellGuardTypography(colors)); dark mode renders pixel-identical.
• Accent swatch border: 30%-white border replaced with colorScheme.outline at 60% — visible in both modes.
• Gateway back-button unclip: circular back button inset 10dp with the border stroke drawn outside the CircleShape clip.
• Nav-graph integrity: the settings_import_export composable is now verified present in the graph (grep-asserted, on-device walkthrough confirmed).

---

🧪 Verification Record

• 101/101 unit tests passing.
• Pre-flight invariants: targetSdk = 36, sqlcipher 4.6.1 (16 KB-aligned ELF segments), jniLibs.useLegacyPackaging = false, FLAG_SECURE on release builds, cleartext restricted to LAN/VPN origins.
• Live device walkthrough (Pixel sailfish, LineageOS): hub navigation → Import & Export → export/restore roundtrip → Appearance theme tiles + cold-restart persistence → Server & Sync status/Gateway → tour cutout → back-button rendering.

---

🛡️ Security Posture — Unchanged

Android KeyStore hardware backing, SQLCipher AES-256 at rest, FLAG_SECURE screen-capture protection on release builds, zero-knowledge sync transport, Android 16 (API 36) + 16 KB page-size kernel ready.

---

ClawStack Mobile Studios©™ — Build features around security, not security around features.

ShellGuard TOTP v0.0.2.0

🦞 ShellGuard TOTP — Release v0.0.2.0 (Build 10)

Milestone 2: The Categorized Settings Hub

███████╗██╗   ██╗███████╗██╗     ██╗              ██████╗   ██╗   ██╗   █████╗    ██████╗     ██████╗
██╔════╝██║   ██║██╔════╝██║     ██║              ██╔═══╝   ██║   ██║  ██╔══██╗  ██╔══██╗    ██╔══██╗
███████╗███████║█████╗   ██║     ██║              ██║ ███╗  ██║   ██║  ███████║  ██████╔╝    ██║   ██║
╚════██║██╔══██║██╔══╝   ██║     ██║              ██║   ██║  ██║   ██║  ██╔══██║  ██╔══██╗    ██║   ██║
███████║██║   ██║███████╗███████╗  ╚██████╔╝╚██████╝  ██║   ██║  ██║   ██║   ██████╔╝
╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝    ╚═╝   ╚═╝   ╚═╝   ╚═╝   ╚═╝   ╚═╝
                                                  ~ **ClawStack Mobile Studios©™** ~

---

🚀 The Core Summary

Welcome to v0.0.2.0 of ShellGuard-TOTP — Milestone 2 of the post-launch expansion. The monolithic settings page is now a fully Categorized Settings Hub: seven preference sections with dedicated sub-screens for Appearance and Behavior, every control backed by structured preference stores that apply changes to the dashboard instantly — no restart, no re-login. 101/101 tests green.

---

💎 Key Themes & Highlights

🎨 1. Categorized Settings Hub

• SettingsMetaScreen: Seven preference categories (🎨 Appearance, ⚡ Behavior, 📦 Icon packs, 🔐 Security, ☁️ Backups, 🛠️ Import & Export, 📈 Audit log) with icons and descriptive subtitles in Reef Modernist cards.
• Honest Roadmap UX: Categories whose sub-screens ship in Phases 12–14 route to clearly-labeled in-app placeholders with a bridge to server/backup settings — no dead ends.

⚡ 2. Preferences Store Architecture (Task 21)

• Structured stores: AppearancePreferences (view mode, issuer icons, next-code preview, expiration blink, digit grouping, issuer/account display rules, Group Manager hidden-groups) and BehaviorPreferences (search scope, focus search on start, minimize on copy, copy on tap, haptics, multiselect groups, highlight & freeze tokens).
• Durable persistence: SharedPreferences-backed StateFlows with corrupt-value fallback and persistence across process recreation; 14 granular setters.
• Regression armor: UserPreferencesStoreTest (5 cases) covering defaults, synchronous flow updates, recreation persistence, group management, and corrupt-enum fallback.

🖌️ 3. Live Dashboard Application (Task 22)

• Digit grouping & haptic feedback drive TotpCard rendering and interaction directly.
• Search scope (All/Local/Synced) and hidden groups filter dashboard streams reactively via combine chains.
• Focus search on start focuses the dashboard search bar through a FocusRequester.
• SettingsAppearanceScreen & SettingsBehaviorScreen: full sub-screens with segmented selectors and switches, all live StateFlow-backed.

---

✅ Verification Gate

• 101/101 unit & Robolectric tests passing (100% green)
• assembleDebug successful
• Live on-device verification: Settings Hub, Appearance & Behavior sub-screens captured from a physical Pixel (README screenshots refreshed)

---

📦 Upgrade Notes

• versionCode 9 → 10 (monotonic Play Console invariant); versionName "0.0.2.0"
• No schema migration required; existing preferences carry over untouched
• Milestone 2 of the post-launch roadmap — next stop: Phase 12 Security Suite (v0.0.2.1)

ShellGuard TOTP v0.0.1.3

🦞 ShellGuard TOTP — Release v0.0.1.3 (Build 9)

The Self-Healing Mirror Hotfix

███████╗██╗   ██╗███████╗██╗     ██╗              ██████╗   ██╗   ██╗   █████╗    ██████╗     ██████╗
██╔════╝██║   ██║██╔════╝██║     ██║              ██╔═══╝   ██║   ██║  ██╔══██╗  ██╔══██╗    ██╔══██╗
███████╗███████║█████╗   ██║     ██║              ██║ ███╗  ██║   ██║  ███████║  ██████╔╝    ██║   ██║
╚════██║██╔══██║██╔══╝   ██║     ██║              ██║   ██║  ██║   ██║  ██╔══██║  ██╔══██╗    ██║   ██║
███████║██║   ██║███████╗███████╗  ╚██████╔╝╚██████╝  ██║   ██║  ██║   ██║   ██████╔╝
╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝    ╚═╝   ╚═╝   ╚═╝   ╚═╝   ╚═╝   ╚═╝
                                                  ~ **ClawStack Mobile Studios©™** ~

---

🚀 The Core Summary

Welcome to v0.0.1.3 of ShellGuard TOTP — a targeted hotfix release patching the v0.0.1.2 remote sync regression where 2FA codes silently stopped syncing from connected ShellGuard Servers, plus a dashboard polish fix for synced code cards. No new features; existing v0.0.1.2 devices self-heal on their next sync pull. All 96 unit tests green.

---

💎 Key Themes & Highlights

🛡️ 1. One-Way Sync Engine Restoration (CRITICAL)

• Root cause patched: v0.0.1.2's delta-sync efficiency compared the nullable local remoteUpdatedAt mirror stamp against the nullable server updated_at field — a null == null match silently classified every affected pearl as "unchanged," skipping decryption and upsert while sync still reported success.
• TotpRepository.classifyDeltaPearls: Extracted the delta classification into a pure, tested function — a pearl is skipped only when a local mirror row exists AND the server stamp is non-null AND equal. Null/missing server stamps always sync (v0.0.1.0 behavior restored).
• Self-healing migration: Devices stuck on v0.0.1.2 require no migration or re-login — the next periodic (6h), pull-to-refresh, or manual sync populates all missing codes automatically.

🎨 2. Synced Card Visual Polish

• Badge wrap fix: The "Read-only" text pill on synced cards wrapped to three lines ("Rea/d-on/ly"), inflating card height. The pink cloud icon now alone denotes synced read-only codes — semantics preserved via contentDescription and the "☁️ Synced from ShellGuard" group header. Cards render at standard single-line height.

🧪 3. Regression Armor

• DeltaSyncClassificationTest (6 cases): First direct coverage of the sync delta path, including the exact production repro (fresh install + null server stamp). Suite total: 96/96 passing.

---

✅ Verification Gate

• 96/96 unit & Robolectric tests passing (100% green)
• assembleDebug build successful
• Live on-device verification: remote sync restored + card layout confirmed on physical Pixel 8

---

📦 Upgrade Notes

• versionCode 8 → 9 (monotonic Play Console invariant); versionName "0.0.1.3"
• No schema migration required; no settings changes
• Recommended for all v0.0.1.2 users immediately

ShellGuard TOTP v0.0.1.2

🦞 ShellGuard-TOTP — Release v0.0.1.2

Expandable Speed Dial FAB, Image QR Decoding Pipeline & Gallery Scanner

███████╗██╗   ██╗███████╗██╗     ██╗              ██████╗   ██╗   ██╗   █████╗    ██████╗     ██████╗ 
██╔════╝██║   ██║██╔════╝██║     ██║              ██╔═══╝   ██║   ██║  ██╔══██╗  ██╔══██╗    ██╔══██╗
███████╗███████║█████╗   ██║     ██║              ██║ ███╗  ██║   ██║  ███████║  ██████╔╝    ██║   ██║
╚════██║██╔══██║██╔══╝   ██║     ██║              ██║   ██║  ██║   ██║  ██╔══██║  ██╔══██╗    ██║   ██║
███████║██║   ██║███████╗███████╗███████╗  ╚██████╔╝╚██████╝  ██║   ██║  ██║   ██║   ██████╔╝
╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝    ╚═════╝   ╚═════╝   ╚═╝  ╚═╝  ╚═╝   ╚═╝   ╚═════╝
                                                  ~ **ClawStack Mobile Studios©™** ~

---

🚀 The Core Summary

Welcome to v0.0.1.2 (Build 8) of ShellGuard-TOTP! This release delivers Phase 10: Expandable Floating Actions Speed Dial (QR, Image & Manual), replacing static dual floating action buttons with an animated, fluid Speed Dial controller.

This update introduces high-throughput image QR decoding using Google ML Kit on Android Storage Access Framework (SAF) image streams, allowing users to scan and import 2FA secret QR codes directly from screenshots and photos in their gallery without needing a secondary camera.

---

💎 Key Themes & Highlights

⚡ 1. Animated Speed Dial FAB (ExpandableSpeedDialFab.kt)

• Fluid 45° Morphing Action: The main action button smoothly morphs from + (collapsed) to ✕ (expanded) with spring-backed physics.
• Semi-Transparent Scrim: Dark alpha backdrop (SpeedDialScrim) provides immediate visual focus on the actions while dimming vault tokens underneath.
• Outside Touch & Back-Handler Dismissal: Tapping anywhere on the scrim or pressing the Android system back button automatically collapses the menu cleanly.

🖼️ 2. High-Throughput ML Kit Image QR Pipeline (ImageQrDecoder.kt)

• Unified Image Vision Engine: Extracts and decodes QR codes from Android URI bitmap streams using Google ML Kit BarcodeScanning.getClient().
• Shared Architecture: Deduplicates vision logic across the codebase by powering both the new dashboard Speed Dial "Scan image" action and the existing QrScannerScreen gallery fallback.
• Instant Ingestion & Toast Feedback: Automatically verifies decoded otpauth:// URIs and adds them directly to the local vault with clear user feedback.

📱 3. Elevated Staggered Action Pills

• Staggered Entrance Animation: Three action pills cascade outward with animated slide-up and fade transitions:
  1. [ 📷 Scan QR code ] — Launches the live CameraX preview scanner with targeting reticle.
  2. [ 🖼️ Scan image ] — Opens the native Android image gallery picker to decode screenshot QR codes.
  3. [ ✏️ Enter manually ] — Opens the manual secret entry form for custom Base32 keys, algorithms (SHA1/SHA256/SHA512), and periods.

🔄 4. One-Way Sync Efficiencies & Protected Mirroring

• Conditional SQL Deletion Guard: Implemented TotpItemDao.deleteByIdIfLocal to atomically enforce local-only deletion at the database query level without requiring an extra pre-fetch read.
• Client-Side Delta Optimization: TotpRepository.syncRemoteVault now compares remote timestamps against local snapshots, skipping expensive AES-GCM decryption for unchanged items while maintaining accurate pruning for server-deleted rows.
• Pull-to-Refresh & ViewModel Protection: Added refreshRemoteVault and strict read-only guards on remote items in TotpViewModel.

🧪 5. Test Suite Oracle Alignment & Stability

• 90/90 Passing Tests: Full test coverage across all unit and Robolectric suites, including 7 new tests in SpeedDialStateTest and ImageQrDecoderTest, plus 4 new tests in OneWaySyncAndReadOnlyProtectionTest.
• Test Oracle Synchronization: Updated UI test selectors in LocalModeUnlockAndVaultTest (scan_qr_fab ➔ speed_dial_fab) ensuring continuous verification alignment.

---

🏗️ Architectural Topology Map

┌─────────────────────────────────────────────────────────────────────────┐
│                     📱 [Grouped Vault Dashboard]                        │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │  📱 Local Vault (is_local_only = 1)                                │  │
│  ├───────────────────────────────────────────────────────────────────┤  │
│  │  ☁️ Synced from ShellGuard (is_local_only = 0, Read-Only)         │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                      │                                  │
│                                      ▼                                  │
│         ┌─────────────────────────────────────────────────────┐         │
│         │        SpeedDialState (BackHandler + Scrim)         │         │
│         └──────────────────────────┬──────────────────────────┘         │
│                                    │                                    │
│         ┌──────────────────────────┴──────────────────────────┐         │
│         │       ExpandableSpeedDialFab (+ ➔ ✕ 45° Morph)      │         │
│         └──────────────────────────┬──────────────────────────┘         │
│                                    │                                    │
│         ┌──────────────────────────┼──────────────────────────┐         │
│         ▼                          ▼                          ▼         │
│  [ 📷 Scan QR ]            [ 🖼️ Scan image ]         [ ✏️ Enter manual ]  │
│  (CameraX Scanner)       (SAF Image Picker)          (AddSecretScreen)  │
│                                    │                                    │
│                                    ▼                                    │
│                         ImageQrDecoder (ML Kit)                         │
│                                    │                                    │
│                                    ▼                                    │
│                        TotpViewModel.importScannedUri                   │
└─────────────────────────────────────────────────────────────────────────┘

---

📦 Changes by Layer

Component	Files	Description
Speed Dial UI	ui/components/ExpandableSpeedDialFab.kt, ui/components/SpeedDialState.kt	Animated FAB with 45° morph, dark dimming scrim, back-handler, and staggered action pills.
Vision & Image Pipeline	scanner/ImageQrDecoder.kt, ui/screens/QrScannerScreen.kt	Shared ML Kit barcode scanning pipeline on URI bitmap streams.
Dashboard Integration	ui/screens/TotpListScreen.kt	Replaced legacy dual FABs and ScannerFab with unified expandable speed dial and SAF gallery launcher.
One-Way Sync Hardening	data/local/dao/TotpItemDao.kt, data/repository/TotpRepository.kt, ui/viewmodels/TotpViewModel.kt	Fast delta comparison, conditional delete SQL, and pull-to-refresh integration.
Cleanups	ui/components/ScannerFab.kt	Removed dead component.
Test Suites	SpeedDialStateTest.kt, ImageQrDecoderTest.kt, LocalModeUnlockAndVaultTest.kt, OneWaySyncAndReadOnlyProtectionTest.kt	Full test coverage verifying interaction transitions, image decoding, sync protections, and updated UI test tags (90/90 passing).

---

📦 Downloads & Artifacts

Asset	Format	Recommended For
shellguard-totp-v0.0.1.2.aab	Android App Bundle	Google Play Console internal test track
shellguard-totp-v0.0.1.2.apk	Standalone Android Package	Direct sideloading & offline verification

---

Engineered with precision by ClawStack Studios.

ShellGuard TOTP v0.0.1.0

🦞 ShellGuard-TOTP — Release v0.0.1.0

Vault Security Orientation, Grouped Local/Remote Dashboard & Spotlight Tour

███████╗██╗   ██╗███████╗██╗     ██╗              ██████╗   ██╗   ██╗   █████╗    ██████╗     ██████╗ 
██╔════╝██║   ██║██╔════╝██║     ██║              ██╔═══╝   ██║   ██║  ██╔══██╗  ██╔══██╗    ██╔══██╗
███████╗███████║█████╗   ██║     ██║              ██║ ███╗  ██║   ██║  ███████║  ██████╔╝    ██║   ██║
╚════██║██╔══██║██╔══╝   ██║     ██║              ██║   ██║  ██║   ██║  ██╔══██║  ██╔══██╗    ██║   ██║
███████║██║   ██║███████╗███████╗███████╗  ╚██████╔╝╚██████╝  ██║   ██║  ██║   ██║   ██████╔╝
╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝    ╚═════╝   ╚═════╝   ╚═╝  ╚═╝  ╚═╝   ╚═╝   ╚═════╝
                                                  ~ **ClawStack Mobile Studios©™** ~

---

🚀 The Core Summary

Welcome to v0.0.1.0 (Build 7) of ShellGuard-TOTP! This release marks the completion of Milestone 1 (Phase 9: Vault Security Education, Enlarged Spotlight Tour & Empty Vault Landing alongside the One-Way Mirror Sync & Grouped Dashboard Refactor).

This update transforms the initial onboarding experience with educational zero-knowledge security cards, an interactive protection mode selector with real-time password strength estimation, Android KeyStore hardware wrapper keys for all modes, clean visual segregation between local on-device and remote synced 2FA codes, and a breathable, physics-based Spotlight guided tour.

---

💎 Key Themes & Highlights

🛡️ 1. Zero-Knowledge Educational Orientation & Hardware Protection

• Vault Security Screen (VaultSecurityScreen.kt): Replaced raw setup screens with a guided orientation explaining client-side encryption, local storage boundaries, and hardware KeyStore isolation.
• Unified Protection Modes: Interactive selector for numeric PIN (4–8 digits) and Master Passwords, featuring a real-time 4-tier entropy strength meter (Weak, Fair, Good, Strong).
• Hardware KeyStore Wrappers: Extended AndroidKeyStoreHelper and AuthRepository with dedicated hardware-backed AES-256-GCM keys (KEY_ALIAS_PIN_WRAPPER, KEY_ALIAS_PASSWORD_WRAPPER) that protect vault secrets at rest in device hardware.
• Biometric Fast-Unlock: Integrated toggle card for instant fingerprint / face authentication.

📱 2. Grouped Local vs Synced Dashboard Architecture

• Distinct Visual Separation: The main dashboard now clearly segregates TOTP items into vertical groups:
  • 📱 Local Vault: High-security tokens created manually or scanned via QR directly on the phone.
  • ☁️ Synced from ShellGuard: Read-only mirrors synced from self-hosted ShellGuard servers.
• One-Way Mirror Sync: Remote connections operate strictly as read-only mirrors of the server. Local codes are never pushed upstream, preventing inadvertent cross-device data leaks.
• Export Integrity: BackupManager exclusively packages Local Codes into encrypted .sgtotp.bak unified archives, preventing remote cache duplication across client backups.

🔦 3. Enlarged Spotlight Guided Tour & Empty Vault Landing

• Spring Geometry Engine: SpotlightOverlay now uses Jetpack Compose Spring.DampingRatioMediumBouncy physics for fluid transitions.
• Breathable Cutouts: Added density-aware radial padding (+18dp) around interactive targets (Settings and Gateway buttons) to eliminate visual crowding.
• Pulsing Cyan Halos: Double-ringed bioluminescent pulse highlighting key action areas.
• Centered Controls: Stacked button layout with a prominent action button and a centered [ Skip Tutorial ] button.
• Empty State Transition: Fresh onboarding lands smoothly on the empty local vault state (TotpEmptyState) with guided quick-action triggers.

---

🏗️ Architectural Topology Map

┌─────────────────────────────────────────────────────────────────────────┐
│                      🌐 [Onboarding & Intake Flow]                       │
│  ┌────────────────────────┐                 ┌────────────────────────┐  │
│  │   IntakeWelcomeScreen  │ ──────────────> │   VaultSecurityScreen  │  │
│  │  (Hero + SAF Import)   │                 │ (Education + Selector) │  │
│  └────────────────────────┘                 └───────────┬────────────┘  │
└─────────────────────────────────────────────────────────┼───────────────┘
                                                          │ (Vault Hatched)
                                                          ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                     📱 [Grouped Vault Dashboard]                        │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │  📱 Local Vault (is_local_only = 1)                                │  │
│  │  • Manual additions • QR scans • SGTOTP backups                   │  │
│  ├───────────────────────────────────────────────────────────────────┤  │
│  │  ☁️ Synced from ShellGuard (is_local_only = 0, Read-Only)         │  │
│  │  • One-way server mirror • Delta synced via Ktor                  │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                 │ (Tour Step 1)                         │
│                                 ▼                                       │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │         SpotlightOverlay (+18dp Spring Radial Geometry)           │  │
│  │  • Highlight Settings ──> Step 2: Highlight Server Gateway        │  │
│  └───────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

---

📦 Changes by Layer

Component	Files	Description
Onboarding & Security UI	ui/screens/onboarding/VaultSecurityScreen.kt, ui/navigation/TotpNavHost.kt	Zero-knowledge educational cards, PIN/Password selector, strength meter, biometric switch, and updated routing.
Guided Tour	ui/components/SpotlightOverlay.kt	Animated spring geometry engine, +18dp breathable radial offset, pulsing halos, stacked actions with centered Skip button.
Dashboard UI	ui/screens/TotpListScreen.kt, ui/viewmodels/TotpViewModel.kt	Grouped vertical streams (Local vs Synced), empty state landing, swipe-to-delete protection on remote items.
Crypto & KeyStore	crypto/AndroidKeyStoreHelper.kt, data/repository/AuthRepository.kt	Dedicated AES-256-GCM hardware wrapper key generation for PIN and Password modes.
Backup Engine	data/backup/BackupManager.kt	Filtered export logic packaging only Local Codes into .sgtotp.bak.
Cleanups	ui/screens/HatchVaultScreen.kt	Removed deprecated vault hatch screen.

---

📦 Downloads & Artifacts

Asset	Format	Recommended For
shellguard-totp-v0.0.1.0.aab	Android App Bundle	Google Play Console internal test track
shellguard-totp-v0.0.1.0.apk	Standalone Android Package	Direct sideloading & offline verification

---

Engineered with precision by ClawStack Studios.

ShellGuard TOTP v0.0.0.2

🦞 ShellGuard-TOTP — Release v0.0.0.2

Welcoming First-Run Intake, Multi-Vault Migration & Sovereign Key Rotation

███████╗██╗   ██╗███████╗██╗     ██╗              ██████╗   ██╗   ██╗   █████╗    ██████╗     ██████╗ 
██╔════╝██║   ██║██╔════╝██║     ██║              ██╔═══╝   ██║   ██║  ██╔══██╗  ██╔══██╗    ██╔══██╗
███████╗███████║█████╗   ██║     ██║              ██║ ███╗  ██║   ██║  ███████║  ██████╔╝    ██║   ██║
╚════██║██╔══██║██╔══╝   ██║     ██║              ██║   ██║  ██║   ██║  ██╔══██║  ██╔══██╗    ██║   ██║
███████║██║   ██║███████╗███████╗███████╗  ╚██████╔╝╚██████╝  ██║   ██║  ██║   ██║   ██████╔╝
╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝    ╚═════╝   ╚═════╝   ╚═╝  ╚═╝  ╚═╝   ╚═╝   ╚═════╝
                                                  ~ **ClawStack Mobile Studios©™** ~

---

🚀 The Core Summary

Welcome to v0.0.0.2 (Build 4) of ShellGuard-TOTP! This milestone deliverable (Phase 7: Welcoming First-Run Wizard & "Import Habitat" Intake Flow) redefines how users board the zero-knowledge privacy fortress. We have introduced an all-new Brand Hero Welcome Screen, one-tap Storage Access Framework (SAF) multi-vault intake, in-memory zero-knowledge sanitization for Bitwarden/Aegis/2FAS backups, native Steam Guard 5-character alphanumeric token calculation, dynamic PIN/Password/Biometrics mode detection, and seamless Key Rotation at Import Time.

---

💎 Key Themes & Highlights

🛡️ 1. Zero-Knowledge Cryptography & Sovereign Key Rotation

• Key Rotation at Import Time: Decoupled backup encryption keys from device vault keys. Users can choose [ 🛡️ Reuse Secret ] for 1-tap fast-track onboarding or [ 🔄 Rotate Key (New) ] to seal their local Android KeyStore under a fresh PIN or Master Password.
• Zero-Knowledge Multi-Vault Ingestion: Pre-validates Bitwarden Vault JSON exports (extracts login.totp and maps folders to Pod categories while 100% stripping passwords and notes in volatile RAM), Bitwarden Authenticator, Aegis, 2FAS, and ShellGuard envelopes.
• Proprietary sgtotp.bak Format: Native adoption of ShellGuard ecosystem standard (.sgtotp.bak / .sgbak) with embedded protection mode metadata, PIN length markers, and biometric flags.
• Resilient Multi-Salt Derivation: Replaced low-level OpenSSL cipher crashes (BAD_DECRYPT) with resilient derivation loops and friendly, actionable user feedback.

🎨 2. Welcoming Brand Hero UI & Physical Security Guidance

• Vector Shield Branding: High-resolution vector ShellGuard launcher shield with ambient bioluminescent backdrop aura and breathing forward navigation FAB.
• Physical Security Notice Card: Prominent zero-knowledge advisory instructing users to manually write down their secret in a physically safe spot, warning that unrecoverable lost secrets seal the vault forever.
• Dynamic Input Form: Decryption bottom sheet automatically presents numeric keypad (KeyboardType.NumberPassword) for PINs and full keyboard (KeyboardType.Password) for Master Passwords with a live segmented override toggle.

🎮 3. Steam Guard 2FA Engine

• 5-Character Alphanumeric Generator: Implemented RFC-compliant Steam Guard token calculation using Steam's custom 26-character Base32 alphabet (23456789BCDFGHJKMNPQRTVWXY).
• Steam URI Parsing: Instant parsing of steam://... URIs mapping directly to algorithm "STEAM" and 5 digits.

🧪 4. Test Oracle & Verification Parity

• 100% Passing Test Suite: 18 comprehensive unit and Robolectric Compose test classes covering encryption at rest, KeyStore envelopes, SQLCipher Room queries, multi-vault sanitization, and UI flows.
• Android 15+ 16 KB Page-Size Ready: SQLCipher 4.6.1 with uncompressed JNI packaging (jniLibs.useLegacyPackaging = false).

---

🏗️ Architectural Topology Map

┌─────────────────────────────────────────────────────────────────────────┐
│              🌐 [First-Run Intake Layer — Jetpack Compose UI]           │
│  ┌────────────────────────┐                 ┌────────────────────────┐  │
│  │   IntakeWelcomeScreen  │ ──────────────> │    HatchVaultScreen    │  │
│  │ (Hero + SAF File Picker)│                 │ (KeyStore Sealed Vault)│  │
│  └───────────┬────────────┘                 └────────────────────────┘  │
│              │ (Selected Backup File URI)                                │
│              ▼                                                          │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │               MultiVaultBackupPreValidator Engine                 │  │
│  │  • ShellGuard (.sgtotp.bak / .sgbak)  • Bitwarden (0% PW Leak)   │  │
│  │  • Aegis Authenticator JSON           • 2FAS Authenticator JSON   │  │
│  └───────────────────────────────────┬───────────────────────────────┘  │
└──────────────────────────────────────┼──────────────────────────────────┘
                                       │ (Decrypted BackupItemDtos in RAM)
                                       ▼
┌─────────────────────────────────────────────────────────────────────────┐
│             🛡️ [Local Storage & Cryptographic Boundary]                 │
│  ┌─────────────────────────────────┐   ┌─────────────────────────────┐  │
│  │    Android KeyStore StrongBox   │   │  SQLCipher 4.6.1 Room DB    │  │
│  │  (AES-256-GCM Master Wrapper)   │   │  (Offline-First Cache)      │  │
│  └─────────────────────────────────┘   └─────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

---

📦 Changes by Layer

Component	Files	Description
Intake & Onboarding UI	ui/screens/onboarding/IntakeWelcomeScreen.kt, ui/onboarding/IntakeViewModel.kt, ui/onboarding/IntakeState.kt	First-run hero welcome screen, SAF document launcher, PIN/Password decryption sheet, and Key Rotation selector.
Migration & Backup Engine	data/backup/MultiVaultBackupPreValidator.kt, data/backup/BackupManager.kt, data/migration/	Schema detection, in-RAM zero-knowledge sanitization, multi-salt derivation, and .sgtotp.bak serialization.
Crypto & Auth Repository	data/repository/AuthRepository.kt, crypto/EncryptedDeviceVault.kt	Active vault secret persistence in KeyStore and retrieval during export/backup operations.
TOTP Engine	engine/TotpEngine.kt, engine/TotpUriParser.kt	Steam Guard 5-character alphanumeric calculation and steam:// URI parser.
Unit & UI Tests	app/src/test/java/com/clawstack/shellguard/totp/*	18 test suites covering engine, encryption, database, and Compose UI flows.

---

📦 Downloads & Artifacts

Asset	Format	Recommended For
shellguard-totp-v0.0.0.2.aab	Android App Bundle	Google Play Console internal test track
shellguard-totp-v0.0.0.2.apk	Standalone Android Package	Direct sideloading & offline verification

---

Engineered with precision by ClawStack Studios.

ShellGuard TOTP v0.0.0.1

🐚 ShellGuard-TOTP v0.0.0.1 — Initial Release

Tagline: "Store and generate 2FA verification codes on your device."
Initial Launch Version: v0.0.0.1 (Build 1)
Google Play Console Track: Internal Testing / Closed Beta

---

🎯 Highlights & Features

🛡️ Privacy-First Zero-Knowledge Architecture

• Hardware-Backed Encryption: Master secret hashes and biometric gates are sealed inside the Android KeyStore using hardware AES-256-GCM (sg_totp_biometric_wrapper).
• Encrypted Local Cache: All 2FA secrets stored at rest in an encrypted Room SQLite database powered by SQLCipher 4.6.1.
• Offline Autonomy: Generates valid 6-digit and 8-digit RFC 6238 TOTP codes 100% offline without requiring continuous network connectivity.
• Screen Shield: Enforces FLAG_SECURE to block screenshots, malware screen recording, and task-switcher recents previews.

🎨 Reef Modernist Mobile Design System

• Dynamic Theming: Signature Reef Pink (BrandLobsterRed #E4048A) default accent with 6 curated palettes (Reef Bioluminescent, Electric Cyan, Imperial Shell, Emerald Bio-Flora, Solar Vent, Minimalist Pearl).
• Adaptive Contrast: Full support for Abyssal Dark, Ocean Mist Light, and System Default appearance modes with adaptive light-mode contrast.
• Live Countdown Arcs: High-precision Canvas countdown ring depleting smoothly with dynamic color alerts (<10s Warning, <5s Danger).
• Tactile Ergonomics: Spring press physics, haptic feedback on code copy, swipe-to-delete gestures, and .imePadding() keyboard handling.

📷 CameraX QR Scanner & Multi-Format Backup

• Live QR Code Scanner: Integrated CameraX with Google ML Kit Barcode Scanning for instant 2FA account setup.
• Gallery Photo Import: Scan QR codes directly from screenshots or saved images.
• Encrypted JSON Backups: Export and restore ShellCrypted AES-256 backup envelopes with SHA-256 integrity checksums.

🌐 Self-Hosted Server Synchronization

• Bidirectional Delta Sync: Two-way push/pull synchronization with self-hosted ShellGuard web servers.
• LAN & VPN Routing: Built-in support for unencrypted HTTP on local private subnets (192.168.x.x, 10.x.x.x) and Tailscale/WireGuard CGNAT VPN tunnels (100.64.0.0/10).
• Interactive Spotlight Tour: Guided visual onboarding walking users through server pairing and settings configuration.

🚀 Android 15+ 16 KB Page-Size Ready

• Built with SQLCipher 4.6.1 and uncompressed JNI packaging (jniLibs.useLegacyPackaging = false) for 16 KB ELF segment alignment on Android 15/16 kernel devices.

---

📦 Downloads & Installation

Asset	Format	Recommended For
shellguard-totp-v0.0.0.1.aab	Android App Bundle	Google Play Console upload / Store distribution
shellguard-totp-v0.0.0.1.apk	Standalone Android Package	Direct sideloading / FOSS distribution

---

Engineered with precision by ClawStack Studios.