Files

2026-02-09 13:06:50 -08:00

20 KiB

Raw Blame History

Sentinel Frontend

A React Native mobile application for secure digital legacy management, built with Expo and TypeScript. Sentinel enables users to preserve, encrypt, and conditionally transfer their digital assets to designated heirs through a sophisticated cryptographic architecture.

Overview
Business Features
Technical Architecture
Security & Cryptography
Getting Started
Project Structure
Configuration
Development

Overview

Sentinel is a comprehensive digital inheritance platform that addresses the critical challenge of preserving and transferring digital assets securely. The application combines advanced cryptographic techniques with an intuitive user interface, ensuring that sensitive information remains protected while enabling controlled access for designated beneficiaries.

Core Value Proposition

Zero-Knowledge Architecture: The platform cannot access user data without cryptographic keys
Conditional Release: Assets are released only when specific conditions are met (e.g., subscription expiration, inactivity)
Multi-Layer Encryption: Combines symmetric and asymmetric encryption for maximum security
Distributed Trust: Uses secret sharing to prevent single points of failure

Business Features

🗞️ Flow - Captain's Journal

An AI-powered journaling interface for daily thoughts, emotions, and reflections.

Capabilities:

Multi-modal entry support: text, voice, and image inputs
AI-inferred emotional state tracking
Conversational AI with multiple role configurations:
- Reflective Assistant: Deep introspection and emotional exploration
- Creative Spark: Brainstorming and creative writing
- Action Planner: Goal setting and productivity coaching
- Empathetic Guide: Emotional support and non-judgmental listening
Archive entries to encrypted Vault for long-term preservation
Conversation summarization for efficient review

Use Cases:

Daily emotional tracking and mental health monitoring
Creative writing and idea generation
Goal planning and accountability
Therapeutic journaling with AI support

📦 Vault - The Deep Vault

End-to-end encrypted storage for sensitive digital assets.

Supported Asset Types:

Game Accounts: Credentials for gaming platforms (Steam, etc.)
Private Keys: Cryptographic keys and wallet seeds
Documents: Legal documents, contracts, and important files
Photos: Personal memories and sensitive images
Wills: Testamentary documents and final wishes
Custom: User-defined asset categories

Security Features:

Biometric authentication required for access (Face ID / Touch ID / Fingerprint)
Shamir's Secret Sharing (3-of-2 threshold) for key management
AES-256-GCM encryption for content protection
User-isolated storage (multi-account support)
Zero-knowledge architecture (server cannot decrypt without user shares)

Workflow:

User creates asset with plaintext content
System generates mnemonic phrase and splits into 3 shares
Content encrypted with derived AES key
One share stored on device, one on server, one for heir
Any 2 shares required to recover decryption key

⚓ Sentinel - Lighthouse Watch

Dead Man's Switch monitoring system for conditional asset release.

Mechanism:

Continuous heartbeat monitoring of user activity
Subscription status tracking
Configurable grace periods before triggering release
Activity logging and audit trail
Status indicators: Normal, Warning, Releasing

Trigger Conditions:

Subscription expiration without renewal
Extended inactivity period
Manual activation by user
Administrative declaration (for testing/emergencies)

Release Process:

System detects trigger condition
Outer encryption layer removed (RSA gateway unlocked)
Heirs notified of available assets
Heirs can claim assets with their share + server share

🧭 Heritage - Fleet Legacy

Heir management and asset distribution system.

Features:

Heir Management: Add, edit, and remove designated beneficiaries
Release Levels: Configure priority tiers (1-3) for asset access
Release Order: Define sequence for multi-heir scenarios
Payment Strategies:
- Prepaid: Heir pays upfront for access
- Pay on Access: Payment required when claiming assets
Legal Document Interface: Formal, testamentary-style presentation
Assignment Workflow: Assign specific assets to specific heirs

Heir Status:

Invited: Heir has been designated but not yet confirmed
Confirmed: Heir has accepted invitation and verified identity

⛵ Me - Captain's Quarters

User account management and system configuration.

Sections:

Subscription Status: Current tier, expiration date, features enabled
Protocol Information: Version tracking and update status
Sentinel Configuration: Heartbeat intervals, grace periods, monitoring settings
Security Center:
- Biometric settings
- Vault state management
- Key recovery options
Data Export: Backup encrypted vault data
Social Responsibility: Program information and participation

Technical Architecture

Technology Stack

Category	Technology	Purpose
Framework	React Native (Expo SDK 52)	Cross-platform mobile development
Language	TypeScript 5.3+	Type-safe development
Navigation	React Navigation 6	Bottom tabs + stack navigation
State Management	React Context API	Authentication and app state
Storage	AsyncStorage	Local persistence (auth tokens, vault state)
Icons	@expo/vector-icons	Feather, Ionicons, FontAwesome5, Material
Styling	StyleSheet + LinearGradient	Custom nautical-themed UI
Crypto	Web Crypto API + Polyfills	Cryptographic operations
AI Integration	LangChain + LangGraph	AI conversation management
Build System	Metro Bundler	JavaScript bundling

Architecture Patterns

Service Layer Architecture

The application uses a modular service architecture for API communication:

src/services/
├── auth.service.ts      # Authentication (login, register)
├── assets.service.ts    # Asset CRUD and inheritance
├── vault.service.ts     # Vault encryption/decryption
├── ai.service.ts        # AI conversation proxy
├── admin.service.ts     # Administrative operations
├── langgraph.service.ts # LangGraph workflow integration
└── storage.service.ts   # AsyncStorage abstraction

Service Pattern:

Centralized API configuration
Mock mode support for development
Consistent error handling
Debug logging integration
Type-safe request/response interfaces

Context-Based State Management

AuthContext (src/context/AuthContext.tsx):

Manages authentication state
Handles token persistence
Provides user information throughout app
Handles initialization and loading states

Usage Pattern:

const { user, token, login, logout, isInitializing } = useAuth();

App (Root)
├── AuthNavigator (if not authenticated)
│   ├── LoginScreen
│   └── RegisterScreen
└── TabNavigator (if authenticated)
    ├── FlowScreen (🗞️)
    ├── VaultScreen (📦)
    ├── SentinelScreen (⚓)
    ├── HeritageScreen (🧭)
    └── MeScreen (⛵)

Key Dependencies

Core:

react: 18.3.1
react-native: 0.76.9
expo: ~52.0.0

Navigation:

@react-navigation/native: ^6.1.18
@react-navigation/bottom-tabs: ^6.6.1
@react-navigation/native-stack: ^6.11.0

Cryptography:

@noble/ciphers: ^1.3.0 (AES encryption)
@noble/hashes: ^1.8.0 (Hash functions)
bip39: ^3.1.0 (Mnemonic generation)
expo-crypto: ~14.0.2 (Crypto polyfills)

AI & Language Models:

@langchain/core: ^1.1.18
@langchain/langgraph: ^1.1.3

Storage & Utilities:

@react-native-async-storage/async-storage: ^2.2.0
buffer: ^6.0.3 (Node.js Buffer polyfill)
readable-stream: ^4.7.0

Security & Cryptography

Encryption Architecture

Sentinel implements a multi-layer encryption system:

Layer 1: Vault Encryption (User-Controlled)

Process:

Generate 12-word BIP-39 mnemonic phrase
Derive AES-256 key using PBKDF2:
- Input: Mnemonic phrase
- Salt: Sentinel_Salt_2026
- Iterations: 100,000
- Hash: SHA-256
- Output: 32-byte AES key
Encrypt plaintext with AES-256-GCM:
- Mode: Galois/Counter Mode (authenticated encryption)
- IV: 16-byte random nonce
- Tag: 16-byte authentication tag
- Output: IV + Ciphertext + Tag (hex encoded)

Implementation: src/utils/vaultCrypto.ts

Shamir's Secret Sharing (3-of-2 Threshold):

Convert mnemonic to entropy (BigInt representation)
Split entropy into 3 shares using linear polynomial:
```
f(x) = secret + a*x (mod P)
```
Where:
- secret: Mnemonic entropy
- a: Random coefficient
- P: Prime modulus (2^127 - 1)
- Shares at x = 1, 2, 3
Share Distribution:
- Device Share (S0): Stored locally on user's device
- Cloud Share (S1): Stored on Sentinel server
- Heir Share (S2): Provided to designated heir
Recovery: Any 2 shares can recover original entropy via Lagrange interpolation

Implementation: src/utils/sss.ts

Layer 3: Gateway Encryption (Server-Controlled)

RSA Outer Encryption:

Server generates RSA-4096 key pair per asset
Inner encrypted content encrypted again with RSA public key
Private key held by server, released only on trigger conditions
Prevents unauthorized access even if inner encryption is compromised

Note: Gateway encryption is handled by backend; frontend sends content_inner_encrypted which backend wraps with RSA.

Key Management

Storage Strategy:

User-isolated keys: getVaultStorageKeys(userId) generates per-user storage keys
Device share (S0): Stored in AsyncStorage with user-scoped key
Mnemonic backup: Optional local backup of mnemonic portion (encrypted)
Multi-account support: Each user has independent vault state

Storage Keys:

{
  INITIALIZED: `sentinel_vault_initialized_u{userId}`,
  SHARE_DEVICE: `sentinel_vault_s0_u{userId}`,
  MNEMONIC_PART_LOCAL: `sentinel_mnemonic_part_local_u{userId}`,
  AES_KEY: `sentinel_aes_key_u{userId}`,
  SHARE_SERVER: `sentinel_share_server_u{userId}`,
  SHARE_HEIR: `sentinel_share_heir_u{userId}`
}

Security Properties

Zero-Knowledge: Server cannot decrypt user data without user's share
Forward Secrecy: Compromising one share reveals nothing about the secret
Authenticated Encryption: GCM mode ensures data integrity
Key Derivation: PBKDF2 with high iteration count prevents brute force
Distributed Trust: No single point of failure for key recovery

Getting Started

Prerequisites

Node.js 18+ and npm
Expo CLI (installed globally or via npx)
iOS Simulator (macOS) or Android Emulator / physical device
Backend API server running (or use NO_BACKEND_MODE)

Installation

# Install dependencies
npm install

# Start Expo development server
npx expo start

Platform-Specific Commands

# iOS Simulator (macOS only)
npm run ios

# Android Emulator / Device
npm run android

# Web Browser
npm run web

Development Modes

With Backend:

Ensure backend server is running (default: http://localhost:8000)
Update API_BASE_URL in src/config/index.ts if needed
Start Expo: npx expo start

Without Backend (Mock Mode):

Set NO_BACKEND_MODE = true in src/config/index.ts
All API calls return mock data
Useful for UI development and testing

Project Structure

frontend/
├── App.tsx                    # Root component with auth routing
├── app.json                   # Expo configuration
├── package.json               # Dependencies and scripts
├── tsconfig.json              # TypeScript configuration
│
├── assets/                    # Static assets
│   ├── icon.png              # App icon (1024x1024)
│   ├── adaptive-icon.png     # Android adaptive icon
│   ├── splash.png            # Splash screen
│   ├── favicon.png           # Web favicon
│   ├── logo.svg              # Vector logo
│   └── images/                # Additional images
│
├── scripts/                   # Build scripts
│   └── generate-icons.js     # Icon generation utility
│
└── src/
    ├── components/            # Reusable UI components
    │   └── common/
    │       ├── BiometricModal.tsx      # Biometric auth modal
    │       ├── Icons.tsx               # Icon helper component
    │       └── VaultDoorAnimation.tsx  # Vault unlock animation
    │
    ├── config/                # Configuration
    │   └── index.ts           # Centralized config (API, endpoints, etc.)
    │
    ├── context/               # React Context providers
    │   └── AuthContext.tsx    # Authentication state management
    │
    ├── hooks/                 # Custom React hooks
    │   ├── index.ts
    │   └── useVaultAssets.ts  # Vault asset management hook
    │
    ├── navigation/            # Navigation configuration
    │   ├── AuthNavigator.tsx  # Login/Register navigation
    │   └── TabNavigator.tsx   # Main app tab navigation
    │
    ├── screens/               # Screen components
    │   ├── FlowScreen.tsx     # AI journaling interface
    │   ├── VaultScreen.tsx    # Encrypted asset management
    │   ├── SentinelScreen.tsx # Dead Man's Switch monitoring
    │   ├── HeritageScreen.tsx # Heir management
    │   ├── MeScreen.tsx       # User settings and account
    │   ├── LoginScreen.tsx    # Authentication
    │   └── RegisterScreen.tsx
    │
    ├── services/              # API service layer
    │   ├── index.ts           # Service exports
    │   ├── auth.service.ts   # Authentication API
    │   ├── assets.service.ts  # Asset CRUD API
    │   ├── vault.service.ts  # Vault encryption utilities
    │   ├── ai.service.ts      # AI conversation API
    │   ├── admin.service.ts   # Admin operations
    │   ├── langgraph.service.ts # LangGraph integration
    │   └── storage.service.ts # AsyncStorage abstraction
    │
    ├── theme/                 # Design system
    │   └── colors.ts          # Color palette and typography
    │
    ├── types/                 # TypeScript type definitions
    │   └── index.ts           # Shared types and interfaces
    │
    ├── utils/                 # Utility functions
    │   ├── index.ts
    │   ├── crypto_core.ts     # Crypto utilities (if needed)
    │   ├── crypto_polyfill.ts # Crypto API polyfills
    │   ├── sss.ts             # Shamir's Secret Sharing
    │   ├── vaultCrypto.ts    # AES encryption/decryption
    │   ├── vaultAssets.ts    # Asset management utilities
    │   ├── token_utils.ts     # Token management
    │   └── async_hooks_mock.ts # Async hooks polyfill
    │
    └── polyfills.ts           # Global polyfills (Buffer, etc.)

Configuration

Environment Configuration

All configuration is centralized in src/config/index.ts:

// Development mode
export const NO_BACKEND_MODE = false;  // Use mock data
export const DEBUG_MODE = true;        // API debug logging

// API Configuration
export const API_BASE_URL = 'http://localhost:8000';
export const API_TIMEOUT = 30000;  // 30 seconds

API Endpoints

Defined in API_ENDPOINTS constant:

Category	Endpoint	Method	Purpose
Auth	`/login`	POST	User authentication
	`/register`	POST	User registration
Assets	`/assets/get`	GET	Fetch user's assets
	`/assets/create`	POST	Create new asset
	`/assets/claim`	POST	Claim inherited asset
	`/assets/assign`	POST	Assign asset to heir
	`/assets/delete`	POST	Delete asset
AI	`/ai/proxy`	POST	AI conversation proxy
	`/get_ai_roles`	GET	Fetch available AI roles
Admin	`/admin/declare-guale`	POST	Admin: Declare user deceased

Vault Storage Configuration

Vault storage uses user-scoped keys for multi-account support:

// Get storage keys for a user
const keys = getVaultStorageKeys(userId);

// Keys are prefixed with user ID to prevent cross-user access
// Format: sentinel_vault_{key}_{suffix}
// Suffix: _u{userId} for authenticated users, _guest for guests

AI Configuration

AI roles and system prompts are configurable:

export const AI_CONFIG = {
  DEFAULT_SYSTEM_PROMPT: '...',
  MOCK_RESPONSE_DELAY: 500,
  ROLES: [
    { id: 'reflective', name: 'Reflective Assistant', ... },
    { id: 'creative', name: 'Creative Spark', ... },
    { id: 'planner', name: 'Action Planner', ... },
    { id: 'empathetic', name: 'Empathetic Guide', ... },
  ]
};

Development

Code Style

TypeScript: Strict mode enabled, all files typed
Components: Functional components with hooks
Naming: PascalCase for components, camelCase for functions/variables
Imports: Absolute imports preferred (configured in tsconfig.json)

Testing

Manual Testing:

Use Expo Go app on physical device for real-world testing
Test biometric authentication on actual devices
Verify encryption/decryption flows with real backend

Mock Mode Testing:

Enable NO_BACKEND_MODE for UI/UX testing
Mock responses simulate real API behavior
Useful for rapid iteration without backend dependency

Debugging

API Debug Logging:

Enabled when DEBUG_MODE = true
Logs all API requests/responses to console
Includes request URLs, headers, and response data

React Native Debugger:

Use React Native Debugger or Chrome DevTools
Inspect component state and props
Monitor network requests

Building for Production

# Build for iOS
eas build --platform ios

# Build for Android
eas build --platform android

# Build for Web
npx expo export:web

Note: Requires Expo Application Services (EAS) account for native builds.

Common Issues

Crypto API Not Available:

Ensure polyfills are loaded (src/polyfills.ts)
Check that crypto.subtle is available in environment
React Native requires polyfills for Web Crypto API

AsyncStorage Errors:

Ensure @react-native-async-storage/async-storage is properly linked
Check storage permissions on device
Clear storage if corrupted: AsyncStorage.clear()

Navigation Issues:

Ensure NavigationContainer wraps navigators
Check that screens are properly registered
Verify tab bar configuration matches screen names

Design Philosophy

Nautical Theme

The application uses a consistent nautical/maritime aesthetic:

Color Palette: Teal (#459E9E) primary, ocean blues, mint gradients
Iconography: Anchors, ship wheels, compasses, lighthouses
Terminology: Captain, Fleet, Vault, Sentinel, Heritage
Typography: Serif fonts for formal sections, sans-serif for UI

User Experience Principles

Privacy First: Encryption happens locally, user controls keys
Transparency: Clear explanation of security mechanisms
Accessibility: Biometric auth for convenience, fallback options available
Elegance: Clean, modern UI with subtle animations
Trust: Visual indicators for security status and system health

License

Support

For issues, questions, or contributions, please contact the development team.

Version: 2.0.0
Last Updated: February 2026

20 KiB Raw Blame History