Package Exports

qclair-quantshield-react-native-android
qclair-quantshield-react-native-android/lib/commonjs/index.js
qclair-quantshield-react-native-android/lib/module/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (qclair-quantshield-react-native-android) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

🛡️ 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:

Receives encrypted requests from the client
Decrypts the request body
Forwards to the original destination
Encrypts the response
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