From dfdd9e761f3ac811b5bb6cc2013af2875c1538ff Mon Sep 17 00:00:00 2001 From: Bruno Deanoz Date: Thu, 18 Jun 2026 17:40:58 +0200 Subject: [PATCH] docs(roadmap): create LATER.md architectural blueprint for future security, KeyStore, and backend sync --- LATER.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 LATER.md diff --git a/LATER.md b/LATER.md new file mode 100644 index 0000000..cd2d4e2 --- /dev/null +++ b/LATER.md @@ -0,0 +1,78 @@ +# Kaizen App — Future Implementation & Architecture Roadmap (LATER) + +This document serves as a persistent repository of high-level architectural blueprints, native security concepts, and backend orchestration models for the **Kaizen Native Android App**. + +To maintain clean execution and avoid technical debt, backend-dependent features and device-level hardware cryptography are documented here for implementation in later phases. + +--- + +## 🛡️ 1. Native Hardware Cryptography & Security + +When transitioning from the Web PWA to the native Android App, we can leverage Android OS-level hardware security that is completely unavailable to standard webbrowsers. + +### A. Android KeyStore System (API 23+) +* **Concept:** Instead of storing API keys or session tokens in plain-text `SharedPreferences` (which are readable on rooted devices), we will use Android's `EncryptedSharedPreferences`. +* **Mechanism:** + - Uses the **hardware-backed KeyStore** (StrongBox / Secure Enclave on flagship devices like the S25 Ultra or Google Pixel 10). + - Automatically encrypts keys and values using AES-256-GCM. + - Encryption keys are kept inside the hardware chip and cannot be leaked even if the OS is compromised or rooted. +* **Orchestration with Backend:** + - Since the Web app encrypts API keys using AES-256 in PostgreSQL, the Android app can either query the decrypted key securely via HTTPS from the backend during a chat leg (if the server acts as the API proxy), OR store a copy of the key locally encrypted in the Android KeyStore for offline direct client-side requests. + +### B. Prevention of Screen Scraping (`FLAG_SECURE`) +* **Concept:** Prevent malware, unauthorized users, or background tasks from taking screenshots or recording the screen on sensitive areas of the app (e.g., chat logs, settings, API-key inputs). +* **Implementation:** + - Set the secure flag dynamically on the Window inside activities or specific composables: + ```kotlin + activity?.window?.addFlags(WindowManager.LayoutParams.FLAG_SECURE) + ``` + - System-wide screenshots are instantly blocked (generates a black image), and the app's preview in the system app-switcher/task-manager is automatically blanked/censored. + +### C. Keystore-Biometrics Binding +* **Concept:** Tie the decryption of chat databases or API keys directly to a successful biometrics authorization. +* **Mechanism:** + - Generate an AES key in the KeyStore that is **specifically configured to require biometrics** (`setUserAuthenticationRequired(true)`). + - The Android CPU's Secure Enclave will literally refuse to release the decryption key to memory unless the native `BiometricPrompt` returns a hardware-validated success signal. + +--- + +## 🔑 2. Biometric Lockscreen & Auth-Sync + +The biometric lockscreen is delayed until the backend sync logic is built, as it requires a secure session verification handshake. + +### A. Instant Biometric Prompt +* **API:** `androidx.biometric.BiometricPrompt` +* **Flow:** On app launch or when selecting a locked chat from the sidebar: + 1. Trigger the native system Biometric prompt (supporting Fingerprint on S25 Ultra, Face Unlock, or PIN fallback). + 2. On success, use the returned cryptographic `Cipher` to decrypt the local DB or session token. + 3. Seamlessly slide into the main interface. + +### B. Translucent Glass PIN-Pad Fallback +* **Design:** For devices without biometrics or on fallback, render a custom, highly blurred frosted-glass PIN-pad. +* **Haptics:** Synchronize each button press with a native, precise tactile click vibration. +* **Visuals:** The `KaizenOrb` floats dynamically above the PIN-pad, glowing red on locked state, breathing in amber on typing, and flashing in bright emerald/amber on successful unlock. + +--- + +## 🌐 3. Backend Synchronization & Streaming Orchestration + +### A. Next.js Session/Cookie Proxy +* **Challenge:** The web app uses Auth.js (NextAuth) with secure `httpOnly` cookies. +* **Solution:** + - The Android app's HTTP client (e.g., Ktor or Retrofit) will maintain a persistent `CookieJar`. + - When logging in via credentials or native Passkeys, the backend sets the Auth.js session cookie, which is automatically attached to subsequent API calls. + +### B. High-Speed WebSocket Streaming +* **Concept:** Instead of polling or standard server-sent events (SSE) which can be unstable on mobile networks, establish a dedicated WebSocket channel for the chat stream. +* **Advantages:** Extremely low latency, full-duplex communication (allows instant interrupt/Stop signals from the client), and perfect synchronization with the breathing frequency of the `KaizenOrb`. + +--- + +## 📈 4. Progressive High-End Visuals + +### A. Ultra HDR with Gainmaps (Android 14+ / API 34) +* **Concept:** Boost highlights (like the shiny glint of the `KaizenOrb` or glowing buttons) to actual HDR peak brightness (up to 1000+ nits) on high-end AMOLED screens. +* **Implementation:** Enable `ActivityInfo.COLOR_MODE_HDR` on the window and write custom AGSL shaders for the glowing canvases. + +### B. Gyroscope-Responsive 3D Parallax +* **Optimization:** Keep the gyroscope tilt listener running on UI thread delays (`SENSOR_DELAY_UI`) and clamp tilt limits tightly. Ensure a complete unregister listener call on app pause to conserve 100% battery efficiency.