44c17b6f9f
Replaces the Phase-0 fakeReply mock with the real v1 API. Deployment-agnostic: one binary, one Authorization: Bearer contract, server-URL field switches between the official instance and any self-host. - auth/LoginScreen: server-URL + email + password -> POST /api/v1/auth/token - net/SecureStore: kzn_ token in EncryptedSharedPreferences (KeyStore AES-256-GCM) - net/SessionViewModel: snapshot-state login/logout routing, restores on launch - net/KaizenApi: POST /api/v1/chat streaming + GET /api/v1/me for the default model - net/StreamConsumer: Kotlin port of lib/chat/stream-consumer.ts (JVM-unit-tested) - deps: okhttp, kotlinx-serialization, security-crypto; INTERNET permission Code-complete; not yet built/run on device (no Android SDK on the dev Mac).
82 lines
5.4 KiB
Markdown
82 lines
5.4 KiB
Markdown
# 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+) — ✅ DONE (Phase 1)
|
|
> Implemented in `net/SecureStore.kt`: the `kzn_` bearer token is stored in
|
|
> `EncryptedSharedPreferences` (AES-256-GCM, KeyStore-backed). Only this item
|
|
> graduated — biometrics binding (§C) and `FLAG_SECURE` (§B) stay deferred.
|
|
|
|
* **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.
|