@appedge/react-native-app

Enhanced React Native App package for AppEdge with advanced device fingerprinting and session management capabilities.

Features

🔒 Device Fingerprinting

• Comprehensive device characteristic collection
• Hardware and software fingerprinting
• Behavioral pattern analysis
• Real-time device change detection
• Risk scoring and anomaly detection

🛡️ Enhanced Session Management

• Device-aware session validation
• Automatic risk assessment
• Multi-device session monitoring
• Security alerts and notifications
• Configurable security thresholds

📱 Cross-Platform Support

• iOS and Android compatibility
• Graceful fallbacks for missing dependencies
• Mock implementations for development
• Production-ready security features

Installation

npm install @appedge/react-native-app

Optional Dependencies (Recommended for full functionality)

# For enhanced device fingerprinting
npm install react-native-device-info @react-native-community/netinfo

# Follow platform-specific setup instructions for:
# - react-native-device-info: https://github.com/react-native-device-info/react-native-device-info
# - @react-native-community/netinfo: https://github.com/react-native-netinfo/react-native-netinfo

Note: The package works without these dependencies but with reduced fingerprinting capabilities using mock implementations.

Quick Start

Basic Setup

import React from 'react';
import { AppProvider } from '@appedge/react-native-app';

export default function App() {
  return (
    <AppProvider
      config={{
        appToken: 'your-app-token',
        // Enable enhanced security features
        enableDeviceFingerprinting: true,
        deviceValidationThreshold: 30, // Risk score threshold (0-100)
      }}
    >
      <YourAppContent />
    </AppProvider>
  );
}

Using Session Management with Device Fingerprinting

import React, { useEffect } from 'react';
import { useSession, useApp } from '@appedge/react-native-app';

function YourAppContent() {
  const { session, sessionValidation, validateSession, validateDevice, getDeviceFingerprint } =
    useSession();

  useEffect(() => {
    // Monitor session validation
    if (sessionValidation) {
      if (!sessionValidation.isValid) {
        console.warn('Session invalid:', sessionValidation.reasons);
      }

      if (sessionValidation.requiresReauth) {
        // Handle re-authentication requirement
        handleReauth();
      }

      if (sessionValidation.deviceChanged) {
        // Handle device changes
        handleDeviceChange();
      }
    }
  }, [sessionValidation]);

  const handleManualValidation = async () => {
    try {
      const validation = await validateSession();
      console.log('Session validation:', validation);
    } catch (error) {
      console.error('Validation failed:', error);
    }
  };

  const handleDeviceInfo = async () => {
    try {
      const fingerprint = await getDeviceFingerprint();
      console.log('Device fingerprint:', fingerprint);
    } catch (error) {
      console.error('Fingerprinting failed:', error);
    }
  };

  return <View>{/* Your app content */}</View>;
}

Configuration Options

AppProvider Config

interface AppEdgeRNConfig {
  appToken: string;
  workerUrl?: string; // Auto-derived if not provided
  region?: 'us' | 'eu' | 'asia'; // Performance optimization
  environment?: 'dev' | 'staging' | 'prod';
  debug?: boolean;

  // Security Settings
  enableDeviceFingerprinting?: boolean; // Default: true
  deviceValidationThreshold?: number; // Default: 30 (0-100)
}

Security Thresholds

• 0-30: Low risk (normal operation)
• 31-70: Medium risk (monitoring required)
• 71-100: High risk (re-authentication recommended)

Device Fingerprinting

What's Collected

The device fingerprinting system collects:

Core Device Info

• Unique device ID
• Brand and model
• Operating system and version
• Build information

Hardware Characteristics

• Total memory and storage
• Screen dimensions and density
• Processing capabilities

Security Indicators

• Emulator detection
• Root/jailbreak status
• System integrity checks

Behavioral Data

• App usage patterns
• Installation timestamps
• Launch frequency

Network & Environment

• Carrier information
• Timezone and locale
• Connection characteristics

Risk Assessment

The system calculates risk scores based on:

• Critical Changes (50 points each): Device ID, bundle ID, brand, model
• Semi-stable Changes (20 points each): OS version, app version, memory
• Dynamic Changes (2 points each): Timezone, carrier, usage patterns
• Security Events (30-40 points): Root detection, emulator detection
• Behavioral Anomalies (10-20 points): Rapid changes, unusual patterns

Session Management

Enhanced Session Interface

interface BaseSession {
  sessionId: string;
  userId?: string;
  token?: string;

  // Device fingerprinting fields
  deviceFingerprint?: string; // Hash of device fingerprint
  deviceRiskScore?: number; // Risk score (0-100)
  deviceLastValidated?: number; // Timestamp
  deviceValidationRequired?: boolean; // Validation flag
}

Session Validation

interface SessionValidationResult {
  isValid: boolean;
  riskScore: number;
  reasons: string[];
  requiresReauth?: boolean;
  deviceChanged?: boolean;
}

Automatic Validation

Sessions are automatically validated:

• On app initialization
• Every 5 minutes during active use
• When device changes are detected
• After 24 hours since last validation

API Reference

Hooks

useSession()

const {
  session,
  deviceId,
  isLoading,
  sessionValidation,
  validateSession,
  getDeviceFingerprint,
  validateDevice,
  refreshSession,
  clearSession,
} = useSession();

useApp()

const app = useApp();

// Enhanced methods
await app.validateDeviceFingerprint();
await app.getDeviceFingerprint();
await app.validateSession();

Device Fingerprint Service

import { DeviceFingerprintService } from '@appedge/react-native-app';

// Generate fingerprint
const fingerprint = await DeviceFingerprintService.generateFingerprint();

// Detect changes
const changes = await DeviceFingerprintService.detectFingerprintChanges();

// Validate device
const validation = await DeviceFingerprintService.validateDevice();

// Clear data
await DeviceFingerprintService.clearFingerprintData();

Security Best Practices

1. Configure Appropriate Thresholds

<AppProvider
  config={{
    enableDeviceFingerprinting: true,
    deviceValidationThreshold: 30, // Adjust based on security needs
  }}
>

2. Handle Security Events

useEffect(() => {
  if (sessionValidation?.requiresReauth) {
    // Force re-authentication
    redirectToLogin();
  }

  if (sessionValidation?.riskScore > 70) {
    // Log security event
    logSecurityEvent(sessionValidation);
  }
}, [sessionValidation]);

3. Monitor Device Changes

useEffect(() => {
  if (sessionValidation?.deviceChanged) {
    // Notify user of device changes
    showDeviceChangeAlert();
  }
}, [sessionValidation]);

4. Implement Progressive Security

const handleHighRiskSession = async () => {
  const validation = await validateSession();

  if (validation.riskScore > 50) {
    // Require additional verification
    await requestAdditionalAuth();
  }

  if (validation.riskScore > 80) {
    // Block access and require full re-authentication
    await forceReauth();
  }
};

Error Handling

Security Errors

import { SecurityError } from '@appedge/react-native-app';

try {
  await getDeviceFingerprint();
} catch (error) {
  if (error instanceof SecurityError) {
    console.error('Security error:', error.message);
    // Handle security-specific errors
  }
}

Graceful Degradation

The package automatically handles missing dependencies:

// Device fingerprinting disabled - still functional
<AppProvider
  config={{
    enableDeviceFingerprinting: false, // Fallback mode
  }}
>

Development vs Production

Development Mode

• Enhanced logging
• Mock implementations for missing dependencies
• Reduced security thresholds
• Debug information exposed

Production Mode

• Minimal logging
• Full security enforcement
• Strict validation thresholds
• Security event monitoring

Migration Guide

From Basic Session Management

// Before
const { session, deviceId } = useSession();

// After - Enhanced with fingerprinting
const { session, deviceId, sessionValidation, validateSession, getDeviceFingerprint } =
  useSession();

// Handle new security features
useEffect(() => {
  if (sessionValidation?.requiresReauth) {
    // Handle re-authentication
  }
}, [sessionValidation]);

Examples

See the complete example in examples/composable-usage.tsx for a full implementation demonstrating:

• Device fingerprinting setup
• Session validation monitoring
• Security event handling
• Risk assessment workflows
• User interface integration

Troubleshooting

Common Issues

1. Missing Dependencies: Install optional packages for full functionality
2. High Risk Scores: Review device validation thresholds
3. Validation Failures: Check device permissions and capabilities
4. Performance: Adjust validation frequency and fingerprinting scope

Debug Mode

Enable debug logging:

<AppProvider
  config={{
    debug: true, // Enable detailed logging
  }}
>

License

MIT License - see LICENSE for details.

Support

For issues and questions:

• GitHub Issues: Report a bug
• Documentation: Full API docs
• Community: Discord