Version: 1.0 · Last Updated: 2026-02-08

Security architecture, threat model, and implementation guidelines for the ObjectStack Mobile client.

1. Security Principles
2. Authentication Security
3. Data Protection
4. Network Security
5. Local Storage Security
6. Session Management
7. Input Validation
8. Error Handling Security
9. Third-Party Dependencies
10. Planned Enhancements
11. Security Checklist

Multiple layers of security controls:

┌─────────────────────────────────────────┐
│  Network Layer                          │
│  (HTTPS, certificate validation)        │
├─────────────────────────────────────────┤
│  Authentication Layer                   │
│  (better-auth, token management)        │
├─────────────────────────────────────────┤
│  Authorization Layer                    │
│  (server-side, planned client-side)     │
├─────────────────────────────────────────┤
│  Data Layer                             │
│  (encrypted storage, input validation)  │
├─────────────────────────────────────────┤
│  Application Layer                      │
│  (error boundaries, safe rendering)     │
└─────────────────────────────────────────┘

• The mobile client only requests the minimum data needed for each view
• Auth tokens are scoped to the authenticated user
• Field projections limit data exposure

• All HTTP communication uses HTTPS
• Tokens are stored in encrypted storage (expo-secure-store)
• No sensitive data is logged or exposed in error messages

1. User authenticates → better-auth issues token
2. Token stored in expo-secure-store (encrypted, hardware-backed)
3. Token read from secure store on app launch
4. Token injected into ObjectStackClient via useMemo
5. Client attaches token to all API requests (Authorization header)
6. On sign-out: token cleared from secure store + client rebuilt

function useProtectedRoute() {
  const { data: session, isPending } = authClient.useSession();
  const segments = useSegments();
  const router = useRouter();

  useEffect(() => {
    if (isPending) return;
    const inAuthGroup = segments[0] === "(auth)";
    if (!session && !inAuthGroup) {
      router.replace("/(auth)/sign-in");
    } else if (session && inAuthGroup) {
      router.replace("/(tabs)");
    }
  }, [session, isPending, segments]);
}

Security guarantees:

• Unauthenticated users cannot access (tabs) or (app) routes
• Authenticated users are redirected away from (auth) routes
• Session check runs on every route change

expo-secure-store         ← Auth tokens ONLY (hardware-backed encryption)
expo-sqlite               ← Business data (offline records, sync queue)
react-native-mmkv         ← Metadata cache (ETags, schema definitions)
Zustand (in-memory)       ← UI state (theme, current app, sync status)
TanStack Query (in-memory)← Server data cache (auto-cleared on sign-out)

When a user signs out, the following data must be cleared:

// 1. Auth tokens
authClient.signOut(); // Clears expo-secure-store

// 2. Offline data
clearAllLocalData(); // Clears expo-sqlite

// 3. Metadata cache
clearMetadataCache(); // Clears MMKV

// 4. Sync queue
clearSyncQueue(); // Clears pending mutations

// 5. In-memory state
// Zustand stores reset, TanStack Query cache cleared

Mobile App ──── HTTPS ──── ObjectStack Server
              │
              ├── Authorization: Bearer <token>
              ├── Content-Type: application/json
              ├── If-None-Match: <etag>  (conditional requests)
              └── User-Agent: ObjectStack-Mobile/1.0

Server errors are parsed into user-friendly messages without exposing:

• Internal server details
• Stack traces
• Database error messages
• API endpoint paths

// lib/error-handling.ts
export function parseError(error: unknown): ObjectStackError {
  // Structured error → mapped to user-friendly message
  // Unknown error → generic "Something went wrong" message
  // Never exposes raw error to user
}

App Launch
    ↓
Check expo-secure-store for token
    ↓
┌── Token exists? ──┐
│                    │
▼ Yes                ▼ No
│                    │
Validate token       Show sign-in
(authClient.useSession)
    ↓
┌── Valid? ──┐
│            │
▼ Yes        ▼ No
│            │
Main app     Clear token
             Show sign-in

All mutations are validated server-side. Client validation is advisory only — the server is the source of truth.

try {
  await create(formData);
} catch (err) {
  const parsed = parseError(err);
  if (parsed.code === "VALIDATION_ERROR") {
    // Show field-level errors from parsed.details
  }
}

Query builder filters are serialized through a type-safe pipeline:

User input → SimpleFilter object → serializeFilter() → ObjectQL AST → Server

No raw user input is sent directly to the server.

1. Never expose internal details — Error messages shown to users are generic
2. Never log sensitive data — No tokens, passwords, or PII in logs
3. Fail safely — ErrorBoundary catches rendering crashes gracefully
4. Structured errors — All errors go through parseError() pipeline

// components/common/ErrorBoundary.tsx
// Catches React rendering errors
// Shows recovery UI with retry button
// Prevents crash from exposing app internals

Every server error code is mapped to a safe, user-friendly message:

const ERROR_MESSAGES: Record<ObjectStackErrorCode, string> = {
  UNAUTHORIZED: "Your session has expired. Please sign in again.",
  FORBIDDEN: "You don't have permission to perform this action.",
  NOT_FOUND: "The requested resource was not found.",
  // ... (no technical details exposed)
};

• All API calls use HTTPS
• Auth tokens stored in expo-secure-store only
• No sensitive data in logs or console output
• Input validation on all form fields
• Error messages are user-friendly (no internals)
• ErrorBoundary wraps all major views

• No hardcoded secrets or API keys
• No eval() or dynamic code execution
• No sensitive data in local storage (only secure store)
• All user input is sanitized before use
• Dependencies checked for known vulnerabilities

• Dependency vulnerability scan passed
• TypeScript strict mode enabled
• ESLint security rules passing
• No development/debug code in production build
• App signing keys properly secured

This document covers the security architecture as of the current implementation. See ARCHITECTURE.md for the overall system architecture and ROADMAP.md for planned security enhancements.