🛡️ QuantShield React Native

Post-quantum encryption SDK for React Native Android applications

Secure your React Native Android app with ML-KEM-1024 (post-quantum) key exchange and AES-256-GCM encryption.

✨ Features

• 🔐 Post-Quantum Security - ML-KEM-1024 (FIPS 203) key encapsulation
• 🔒 AES-256-GCM Encryption - Authenticated encryption with associated data
• 🚀 Easy Integration - Just 3 methods to use
• ⚡ Native Performance - Powered by BouncyCastle crypto library
• 🔄 Automatic Proxy Routing - All HTTP requests automatically routed through QuantShield proxy
• 📱 Android Support - API 21+ (Android 5.0+)

📋 Requirements

• React Native >= 0.60.0
• Android API >= 21 (Android 5.0+)
• Node.js >= 16

🚀 Installation

npm install qclair-quantshield-react-native-android

The package includes all dependencies - no additional setup required!

📖 Quick Start

1. Initialize

import QuantShield from 'qclair-quantshield-react-native-android';

// Option 1: Use fetch() for HTTP requests
await QuantShield.initialize('https://your-server.com', {
  autoProtect: true,        // Auto-intercept fetch() calls (default: true)
  allowedDomains: ['api.example.com']  // Optional: only intercept these domains
});

// Option 2: Use Axios (RECOMMENDED - Order-independent!)
import axios from 'axios';

await QuantShield.initialize('https://your-server.com', {
  autoProtect: false  // Don't auto-patch, we'll patch Axios manually
});

// Apply Axios patch - works anytime, anywhere!
// Client code can register interceptors before or after this call
QuantShield.applyAxiosPatch(
  axios,
  'https://your-server.com/decrypt-and-forward',
  ['api.example.com']
);

// Your interceptors can be registered before or after - doesn't matter!
axios.interceptors.request.use((config) => {
  config.headers['Authorization'] = 'Bearer token';
  return config;  // QuantShield will encrypt this ✅
});

// Option 3: Use raw XMLHttpRequest (less common)
await QuantShield.initialize('https://your-server.com', {
  autoProtect: true,
  patchXHR: true,          // Enable XMLHttpRequest patching
  allowedDomains: ['api.example.com']
});

console.log('QuantShield initialized!');

💡 Axios Users: The applyAxiosPatch() method is bulletproof - it works regardless of when you call it (before, after, or during interceptor registration). It automatically maintains proper execution order. See Axios Integration Guide for details.

2. Encrypt Data

// Encrypt data
const encrypted = await QuantShield.encryptData('Hello World');
console.log('Encrypted:', encrypted);

3. Decrypt Data

// Decrypt data
const decrypted = await QuantShield.decryptData(encrypted);
console.log('Decrypted:', decrypted);

� How Proxy Routing Works

When autoProtect: true is enabled, QuantShield automatically intercepts all HTTP requests:

Before QuantShield:

fetch('https://api.example.com/users')  // → Direct to api.example.com

After QuantShield:

fetch('https://api.example.com/users')  // → Intercepted and routed to:
                                       //   https://your-server.com/decrypt-and-forward
                                       //   (with X-Original-URL: https://api.example.com/users)

Your QuantShield server acts as a proxy that:

1. Receives encrypted requests from the client
2. Decrypts the request body
3. Forwards to the original destination
4. Encrypts the response
5. Returns encrypted response to client

�📚 Complete Example

import React, { useEffect, useState } from 'react';
import { View, Text, Button, Alert } from 'react-native';
import QuantShield from 'qclair-quantshield-react-native-android';

export default function App() {
  const [initialized, setInitialized] = useState(false);

  useEffect(() => {
    initializeQuantShield();
  }, []);

  const initializeQuantShield = async () => {
    try {
      const result = await QuantShield.initialize('https://your-server.com', {
        autoProtect: true,  // Auto-encrypt fetch() calls
        allowedDomains: ['api.example.com']
      });
      console.log('✅ Initialized! UID:', result.uid);
      
      // Optional: Enable automatic key rotation
      QuantShield.enableAutoRefresh(10); // Refresh every 10 minutes
      
      setInitialized(true);
    } catch (error) {
      console.error('❌ Initialization failed:', error);
    }
  };

  const testEncryption = async () => {
    try {
      // Encrypt
      const plainText = 'My secret message';
      const encrypted = await QuantShield.encryptData(plainText);
      console.log('Encrypted:', encrypted);

      // Decrypt
      const decrypted = await QuantShield.decryptData(encrypted);
      console.log('Decrypted:', decrypted);

      Alert.alert('Success!', `Original: ${plainText}\nDecrypted: ${decrypted}`);
    } catch (error) {
      Alert.alert('Error', error.message);
    }
  };

  return (
    <View style={{ flex: 1, justifyContent: 'center', padding: 20 }}>
      <Text style={{ fontSize: 20, marginBottom: 20, textAlign: 'center' }}>
        QuantShield Demo
      </Text>
      {initialized ? (
        <Button title="Test Encryption" onPress={testEncryption} />
      ) : (
        <Text style={{ textAlign: 'center' }}>Initializing...</Text>
      )}
    </View>
  );
}

🔧 API Reference

initialize(serverUrl, options?)

Initialize QuantShield and perform ML-KEM-1024 handshake.

const result = await QuantShield.initialize('https://server.com', {
  autoProtect: true,       // Auto-encrypt fetch() calls (default: true)
  patchXHR: false,        // Enable XMLHttpRequest patching for Axios (default: false)
  allowedDomains: []      // Domains to intercept (empty = all domains)
});

Options:

• autoProtect (boolean): Automatically intercept and encrypt HTTP requests. Default: true
• patchXHR (boolean): Enable XMLHttpRequest patching for Axios/XHR-based libraries. Default: false
  • Set to false if using only fetch() (recommended)
  • Set to true if using Axios or other XHR-based HTTP clients
• allowedDomains (string[]): List of domains to intercept. Empty array = intercept all domains.

Returns:

{
  success: boolean;  // Handshake success
  uid: string;       // Session UID
  cached: boolean;   // Whether session was restored from cache
}

Important:

• By default, only fetch() is patched to avoid conflicts with fetch polyfills
• Enable patchXHR: true only if you're using Axios or other XMLHttpRequest-based libraries
• Don't mix fetch() and Axios if both patches are enabled - use one or the other

encryptData(data)

Encrypt string data with AES-256-GCM.

const encrypted = await QuantShield.encryptData('Hello World');

Returns: string (Base64 URL-safe encrypted data)

decryptData(encryptedData)

Decrypt string data with AES-256-GCM.

const decrypted = await QuantShield.decryptData(encrypted);

Returns: string (Decrypted plain text)

getStatus()

Get current initialization status.

const status = await QuantShield.getStatus();
// { initialized: boolean, hasSessionKey: boolean, uid: string }

reset()

Clear stored keys and reset state.

await QuantShield.reset();

🔄 Automatic Key Rotation

Enable automatic key refresh to rotate encryption keys periodically for enhanced security.

enableAutoRefresh(intervalMinutes?)

Start automatic key rotation at specified intervals.

// Enable auto-refresh every 10 minutes (default)
QuantShield.enableAutoRefresh(10);

// Or customize the interval
QuantShield.enableAutoRefresh(5);  // Every 5 minutes
QuantShield.enableAutoRefresh(30); // Every 30 minutes

Parameters:

• intervalMinutes (optional): Number of minutes between key refreshes. Default: 10

Example with React Native lifecycle:

import React, { useEffect } from 'react';
import QuantShield from 'qclair-quantshield-react-native-android';

export default function App() {
  useEffect(() => {
    // Initialize QuantShield
    const init = async () => {
      await QuantShield.initialize('https://your-proxy.com', {
        autoProtect: true,
        allowedDomains: ['api.example.com']
      });
      
      // Enable auto-refresh after initialization
      QuantShield.enableAutoRefresh(10);
    };
    
    init();
    
    // Cleanup on unmount
    return () => {
      QuantShield.disableAutoRefresh();
    };
  }, []);

  return <YourApp />;
}

disableAutoRefresh()

Stop automatic key rotation.

QuantShield.disableAutoRefresh();

Benefits of Auto-Refresh:

• ✅ Enhanced Security: Fresh encryption keys at regular intervals
• ✅ Reduced Attack Window: Compromised keys have limited validity
• ✅ Non-Blocking: Runs in background without interrupting requests
• ✅ Automatic: No manual intervention required
• ✅ Safe: Prevents concurrent refreshes

Note: Each refresh generates a new UID and encryption key. The old session is replaced seamlessly.

🌐 Auto HTTP Interception

When autoProtect: true (default), HTTP requests are automatically encrypted/decrypted.

Using fetch() (Recommended)

// Initialize with fetch support (default)
await QuantShield.initialize('https://server.com', { 
  autoProtect: true  // patchXHR defaults to false
});

// All fetch calls are now encrypted automatically!
const response = await fetch('https://api.example.com/data', {
  method: 'POST',
  body: JSON.stringify({ message: 'Hello' })
});
// ↑ Request body is encrypted before sending
// ↓ Response is decrypted before returning

const data = await response.json();
console.log(data); // Decrypted data

Using Axios (Requires XHR Patching)

import axios from 'axios';

// Initialize with XHR patching for Axios
await QuantShield.initialize('https://server.com', { 
  autoProtect: true,
  patchXHR: true  // Enable XMLHttpRequest patching
});

// Axios requests are now encrypted automatically!
const response = await axios.post('https://api.example.com/data', {
  message: 'Hello'
});

console.log(response.data); // Decrypted data

Important Notes

• fetch() vs Axios: Choose one approach for your app

  • Use fetch() if possible (native, modern, default support)
  • Use patchXHR: true only if you need Axios or other XHR-based libraries
  • Don't enable patchXHR if using only fetch() to avoid conflicts

• Selective Interception: Use allowedDomains to intercept specific domains only

  await QuantShield.initialize('https://server.com', { 
    autoProtect: true,
    allowedDomains: ['api.example.com', 'secure-api.com']
  });

🔐 Security

Cryptographic Algorithms

• Key Exchange: ML-KEM-1024 (Module-Lattice-Based KEM, FIPS 203)
• Encryption: AES-256-GCM (Galois/Counter Mode)
• Key Derivation: HKDF-SHA256 (RFC 5869)
• Library: BouncyCastle 1.78

Post-Quantum Security

ML-KEM (formerly CRYSTALS-Kyber) is a NIST-standardized post-quantum cryptographic algorithm designed to be secure against attacks by quantum computers.

🛠️ Troubleshooting

Android Build Issues

If you encounter build issues:

cd android
./gradlew clean
cd ..
npm run android

Module Not Found

Ensure auto-linking is working:

npx react-native-clean-project
npm install

For manual linking (React Native < 0.60):

npx react-native link qclair-quantshield-react-native-android

📦 What's Included

The package includes:

• ✅ Native Android bridge (Kotlin)
• ✅ Pre-compiled crypto.jar with ML-KEM + AES-GCM
• ✅ All dependencies (Gson, OkHttp, BouncyCastle)
• ✅ TypeScript type definitions
• ✅ Auto HTTP interception

🔄 Version History

See CHANGELOG.md for version history.

📄 License

MIT License - see LICENSE file for details.

🤝 Support

For issues and questions:

• GitHub Issues: Report a bug
• Documentation: Quick Reference

🚧 Platform Support

| Platform | Support | |----------|---------| | Android | ✅ Supported (API 21+) | | iOS | ⏳ Coming soon | | Web | Use qclair-quantshield-js |

Made with ❤️ for secure mobile communications