ChatApp/docs/superpowers/specs/2026-05-13-mobile-phase-1-auth-chat-mvp-design.md

Mobile Phase 1 — Auth + Chat MVP

Date: 2026-05-13 Scope: apps/mobile Roadmap context: 2026-05-13-mobile-deployment-roadmap.md

---

Problem

Phase 0 delivered a Netralax-branded shell. It boots, renders a placeholder, and is configured for eas build, but the app has no actual functionality. To call mobile "deployment-ready with working features" the user must be able to log in, see their chats, and send a text message — the smallest end-to-end vertical slice that's also useful.

Goal

After Phase 1, a Netralax user on iOS or Android can:

1. Open the app, enter their account email, request a magic link.
2. Tap the link in their email (deep link returns to netralax://auth/callback), complete the session, and land on the chat list.
3. See their existing conversations (DMs + groups) with last-message previews, decrypted on-device.
4. Open a conversation, see the message history (decrypted), and send a new text message that the desktop client receives correctly.
5. Log out from a settings entry, returning to the login screen.

Non-goals

• Signup with invite code (login-only MVP — accounts are provisioned via desktop or admin scripts).
• Attachments, voice messages, reactions, edits (Phase 2).
• Calls (Phase 3).
• Push notifications (deferred — chat works without push, the user pulls fresh data on screen focus / pull-to-refresh).
• Realtime subscription on conversations (deferred). Phase 1 polls / refetches on screen focus.
• Read receipts, typing indicator, presence (Phase 2).
• Friend list, profile edit, settings beyond logout.

Design

1. Theme constants

apps/mobile/theme/colors.ts exports a flat colors object with the hex codes Phase 0 inlined across files (#0b0b0f, #9ca3af, #fff, #6b7280, #5865f2) plus a couple of new ones we need for Phase 1 (input border, danger). Every Phase 1 screen imports from here; no new hex literals appear in components.

2. Crypto adapter (apps/mobile/lib/cryptoBackend.ts)

A near-mirror of apps/desktop/src/lib/cryptoBackend.ts but wrapping react-native-libsodium instead of libsodium-wrappers-sumo. The two libraries expose the same primitive API (the RN port re-exports the libsodium-wrappers types) — only the import + the absence of _sodium.ready differs. Synchronous (no WASM warm-up needed on a native lib). Registered at boot via crypto.setCryptoBackend(createLibsodiumBackend()) from _layout.tsx.

3. Secret store adapter (apps/mobile/lib/secretStore.ts)

Implements SecretStore (from @chat-app/shared/auth/secure-storage) backed by expo-secure-store. Per the contract, values are Uint8Array; we base64-encode at the boundary because SecureStore only accepts strings. buffer polyfill is part of RN's base set, no extra install.

4. Supabase session storage (apps/mobile/lib/sessionStorage.ts)

Supabase's JS client needs an async-storage object for session tokens. Use @react-native-async-storage/async-storage (new dep) — supabase-js v2 accepts its getItem / setItem / removeItem API directly.

5. Env config (apps/mobile/lib/env.ts)

Expo exposes vars prefixed EXPO_PUBLIC_* to the bundle via process.env. Read three:

• EXPO_PUBLIC_SUPABASE_URL
• EXPO_PUBLIC_SUPABASE_ANON_KEY
• EXPO_PUBLIC_AUTH_REDIRECT_URL — defaults to netralax://auth/callback.

apps/mobile/.env.example is added with placeholder values + a README pointer.

6. Supabase client (apps/mobile/lib/supabase.ts)

Mirrors desktop's apps/desktop/src/lib/supabase.ts. Calls createClient from @chat-app/shared/supabase with the mobile sessionStorage adapter and detectSessionInUrl: false (the callback screen parses the URL manually).

7. Auth context (apps/mobile/lib/authContext.tsx)

React Context provider that wraps the authenticated tree. Exposes:

• session: Session | null
• user: User | null
• device: DeviceRecord | null — the registered device for this install
• loading: boolean — true while hydrating from AsyncStorage on boot
• signOut(): Promise<void>

On mount:

1. await supabase.auth.getSession() — pulls from AsyncStorage.
2. If a session exists, derive the device by listOwnDevices(supabase) and matching on a locally-stored device id (in secretStore under key device.id).
3. If session exists but no device record yet (fresh install, account exists on other devices), call registerDevice with a fresh key pair, store the new device id + private key in secretStore.

The provider subscribes to supabase.auth.onAuthStateChange so signing out from anywhere updates the tree.

8. Route gating

• app/index.tsx: if session is set, redirect to /(app)/chats. Otherwise show the login form.
• app/(app)/_layout.tsx: if no session, redirect to /. (Existing file: change from "always render Stack" to "guard on session".)

9. Login screen (app/index.tsx)

Replaces the Phase-0 placeholder. Renders:

• Netralax wordmark.
• Email TextInput.
• "Magic Link senden" button → auth.loginWithMagicLink(supabase, email, env.authRedirectUrl).
• After tap: show "Check deine Mails" state until the deep link fires.
• Error banner on failure.

10. Auth callback (app/auth/callback.tsx)

A new screen reachable via the netralax://auth/callback deep link. Reads URL params (Supabase magic-link callback puts access_token + refresh_token in the URL hash or query), calls supabase.auth.setSession({...}), routes to /(app)/chats. On failure, routes back to / with an error message.

Expo Router auto-handles the deep link → screen mapping when the scheme in app.json matches and the path matches the route file.

11. Conversation list (app/(app)/chats.tsx)

Replaces the Phase-0 placeholder. Uses chat.listConversations(supabase) from @chat-app/shared/chat. Renders a FlatList of ConversationRow (new component):

• DM: peer's display name + Avatar (initial-letter circle).
• Group: group name + "N Mitglieder".
• Last message preview — decrypted via decryptMessages if encrypted, else "…".
• Timestamp (relative — "Vor 5 Min").

Pull-to-refresh refetches.

Tap on row → navigates to /(app)/conversations/[id].

A small icon-button in the header opens a logout modal calling signOut().

12. Conversation detail (app/(app)/conversations/[id].tsx)

Loads:

• fetchConversationMessages(supabase, { conversationId, limit: 50 }).
• listConversationDeviceKeys(supabase, conversationId) for decryption.
• decryptMessages({ messages, deviceKeys, myDeviceId, myPrivateKey }) to get plaintext.

Renders an inverted FlatList (newest at the bottom, like Discord). Each row shows sender name + body + timestamp. Attachments rendered as "📎 [Anhang]" placeholders — Phase 2 adds real rendering.

Bottom: a TextInput + send button. On send: sendEncryptedMessage. Optimistically appends to local state, then refetches.

13. Cleanup

• Delete apps/mobile/lib/sharedSmoke.ts and the void sharedSmoke import in _layout.tsx.

File structure (after Phase 1)

apps/mobile/
├── app/
│   ├── _layout.tsx           ← MODIFIED: register crypto backend, mount AuthProvider
│   ├── index.tsx             ← MODIFIED: Login screen (magic link form)
│   ├── auth/
│   │   └── callback.tsx      ← NEW: deep-link landing
│   └── (app)/
│       ├── _layout.tsx       ← MODIFIED: session-gated stack
│       ├── chats.tsx         ← MODIFIED: real conversation list + logout
│       └── conversations/
│           └── [id].tsx      ← NEW: conversation view + send
├── components/
│   ├── ErrorBoundary.tsx     ← unchanged
│   ├── Avatar.tsx            ← NEW: initial-letter avatar circle
│   └── ConversationRow.tsx   ← NEW: list row
├── lib/
│   ├── authContext.tsx       ← NEW
│   ├── cryptoBackend.ts      ← NEW
│   ├── env.ts                ← NEW
│   ├── secretStore.ts        ← NEW
│   ├── sessionStorage.ts     ← NEW
│   ├── supabase.ts           ← NEW
│   ├── timeFormat.ts         ← NEW
│   └── sharedSmoke.ts        ← DELETED
├── theme/
│   └── colors.ts             ← NEW
├── .env.example              ← NEW
└── package.json              ← MODIFIED: + @react-native-async-storage/async-storage

Risks

• react-native-libsodium New Architecture compatibility. v1.7 claims Fabric/TurboModule support. If setCryptoBackend(createLibsodiumBackend()) crashes on app boot under New Arch, fall back to "newArchEnabled": false and re-evaluate.
• @chat-app/shared ESM resolution under Metro. Shared emits ESM with .js import specifiers. Metro's default resolver handles this; if it doesn't, set metro.config.js's resolver.unstable_enablePackageExports: true.
• Magic-link deep-link return. Expo Router auto-maps netralax://auth/callback to app/auth/callback.tsx since the scheme in app.json matches (netralax) and expo-linking is in the prebuild.
• Device key persistence. The private key blob lives in expo-secure-store (Keychain on iOS, Keystore on Android). Uninstalling the app wipes the key — same as desktop. Backup/restore is post-Phase-4.

Verification (manual on real hardware after typecheck passes)

1. pnpm --filter @chat-app/mobile typecheck → exit 0.
2. .env.local populated with the same SUPABASE_URL / SUPABASE_ANON_KEY the desktop uses → app boots, shows Login.
3. Enter an existing-user email → "Magic Link senden" succeeds → "Check deine Mails" state appears.
4. Open the email link on the device → callback URL fires Expo Router → app navigates to /(app)/chats.
5. Chat list loads; existing DMs and groups from the desktop are visible with decrypted previews.
6. Tap a conversation → detail screen opens, history loads, decrypted message bodies render newest-at-bottom.
7. Type "test from mobile" → send → desktop client of the same account sees the new message via Supabase realtime.
8. Pull-to-refresh on chat list re-fetches.
9. Tap settings → "Abmelden" → returns to Login screen, session cleared from AsyncStorage.

Out of scope

• Push notifications (expo-notifications + notify-push edge function).
• Realtime subscription on the mobile side (relies on focus-refetch).
• Conversation creation (new DM / new group) from mobile.
• Attachments, voice messages, reactions, edits, replies, forwards (Phase 2).
• Read receipts, typing, delivery state (Phase 2).
• Voice/video calls (Phase 3).
• Backup/restore device keys (post-Phase-4).
• Profile editing, friends, admin tools (post-Phase-4).