@ideem/zsm-react-native/README.md

ZSM makes 2FA easy and invisible for everyone, all the time, using advanced cryptography like MPC to establish cryptographic proof of the origin of any transaction or login attempt, while eliminating opportunities for social engineering. ZSM has no relian

# ZSM React Native Module

React Native module for FIDO2 and UMFA authentication using ZSM (Zero-knowledge Secure Multi-party computation).

## Source File Management

**IMPORTANT**: The JavaScript source files in this module are automatically copied from the base implementation during the build process. Do not edit the files in the `src/` directory directly.

### Source Files Location

The core JavaScript files are copied from:
```
/platforms/javascript/zsm-client-base/src/
```

**Source files copied during build:**
- `webauthn-client-base.js` - Core WebAuthn client implementation
- `relying-party.js` - Relying Party API client
- `umfa-client.js` - UMFA client wrapper
- `zsm-logger.js` - Logging utilities
- `OPTIMIZED-FLOW.md` - Flow documentation

### Build Process

The source files are automatically copied during the build process via:
```bash
npm run copy-source  # Copies files from ../../../javascript/zsm-client-base/src/*.js
npm run build        # Compiles with Babel to lib/ directory
```

**To make changes to the JavaScript code:**
1. Edit files in `/platforms/javascript/zsm-client-base/src/`
2. Run `npm run copy-source && npm run build` in this directory
3. Test changes in React Native apps

## React Native Architecture

### WebAuthn Client Extension

The `webauthn-client.js` file in this module extends `webauthn-client-base.js` with React Native-specific functionality:

```javascript
import WebAuthnClientBase from './webauthn-client-base';
import { NativeModules } from 'react-native';

class WebAuthnClient extends WebAuthnClientBase {
    // Inherits all base functionality from webauthn-client-base.js
    
    // Adds React Native native bridge integration
    getZsmApi = async (config) => {
        const { ZSMNativeModule } = NativeModules;
        return await ZSMNativeModule.initializeZSM(config);
    }
}
```

### Key Features

#### Base Functionality (from webauthn-client-base.js)
- **UMFA Optimized Flow**: Implements optimized enrollment and authentication flows
- **Identity Management**: Handles identity_id and consumer_id mapping for MPC operations
- **WebAuthn Operations**: Core WebAuthn create, get, and retrieve operations
- **Relying Party Integration**: HTTP API client for authenticator server
- **Error Handling**: Comprehensive error handling and logging

#### React Native Extensions (from webauthn-client.js)
- **Native Bridge**: Connects to native Android/iOS ZSM libraries via React Native bridge
- **Platform Integration**: Seamless integration with React Native app lifecycle
- **Device Storage**: Native secure storage for credentials and keys
- **Biometric Integration**: Native biometric authentication support

### Native Module Integration

The React Native module bridges to native implementations:

**Android**: 
- `ZSMNativeModule.kt` - Kotlin bridge to ZSM.aar Android library
- Uses native Android keystore and biometric APIs

**iOS**: 
- `ZSMNativeModule.m` - Objective-C bridge to ZSM.xcframework iOS library  
- Uses native iOS keychain and biometric APIs

## Developer Setup

### Prerequisites

To build this module from source, you need:

1. **Node.js** (18.0.0 or higher)
2. **Rust** toolchain: Install from https://rustup.rs/
3. **Android SDK** for Android builds:
   ```bash
   # Set environment variables (add to ~/.zshrc or ~/.bash_profile)
   export ANDROID_HOME=/path/to/your/android/sdk
   export ANDROID_SDK_ROOT=$ANDROID_HOME
   export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools
   ```
4. **Xcode** for iOS builds (macOS only)

### Quick Start

1. **Clone and install dependencies:**
   ```bash
   cd platforms/react/modules/zsm-react-native
   npm install
   ```

2. **The module will automatically build mobile dependencies** during npm install. If you encounter build errors, ensure all prerequisites are installed.

3. **Force rebuild if needed:**
   ```bash
   ./build_dependencies.sh --force
   ```

### Using in React Native Apps

The module is automatically configured for apps in this repository:

```bash
cd platforms/react/apps/umfa
npm install  # Automatically installs and builds zsm-react-native
npm run android  # or npm run ios
```

## Legal
Copyright (C) Ideem, Inc. - All Rights Reserved

## Support
You can receive support and get your questions answered by emailing <a href="mailto:support@useideem.com">support@useideem.com</a>.