qclair-quantshield-react-native-android/src/index.d.ts

🛡️ Post-quantum encryption for React Native Android apps. ML-KEM + AES-GCM encryption with automatic proxy routing and key rotation. (Android only - iOS coming soon)

declare module 'qclair-quantshield-react-native-android' {
  /**
   * Initialization options for QuantShield
   */
  export interface InitializeOptions {
    /**
     * Automatically apply HTTP patches (fetch and XMLHttpRequest)
     * @default true
     */
    autoProtect?: boolean;

    /**
     * Enable XMLHttpRequest patching (for Axios and XHR-based libraries)
     * Set to false if using only fetch() to avoid conflicts
     * @default false
     */
    patchXHR?: boolean;

    /**
     * Array of domains to intercept. If empty, all domains are intercepted.
     * @example ['api.example.com', 'secure.api.com']
     */
    allowedDomains?: string[];
  }

  /**
   * Result returned from handshake operation
   */
  export interface HandshakeResult {
    /**
     * Whether handshake was successful
     */
    success: boolean;

    /**
     * Unique session identifier
     */
    uid: string;

    /**
     * Whether session was restored from cache (not a new handshake)
     */
    cached: boolean;
  }

  /**
   * Decrypted response structure
   */
  export interface DecryptedResponse {
    /**
     * Response body (usually JSON string)
     */
    body: string;

    /**
     * HTTP status code
     */
    status_code: number;

    /**
     * HTTP status text
     */
    status: string;

    /**
     * Response headers
     */
    headers?: Record<string, string>;
  }

  /**
   * QuantShield API interface
   */
  interface QuantShieldAPI {
    /**
     * Initialize QuantShield with automatic protection
     * 
     * @param serverUrl - URL of your QuantShield proxy server
     * @param options - Optional configuration
     * @returns Promise that resolves to true when initialized
     * 
     * @example
     * ```typescript
     * await QuantShield.initialize('https://your-proxy.com', {
     *   autoProtect: true,
     *   allowedDomains: ['api.example.com']
     * });
     * ```
     */
    initialize(serverUrl: string, options?: InitializeOptions): Promise<boolean>;

    /**
     * Perform ML-KEM-1024 handshake with server
     * 
     * @param serverUrl - URL of your QuantShield server
     * @param forceNew - Force new handshake even if session exists (default: false)
     * @returns Promise with handshake result
     * 
     * @example
     * ```typescript
     * const result = await QuantShield.initializeHandshake('https://your-proxy.com');
     * console.log('Session UID:', result.uid);
     * ```
     */
    initializeHandshake(serverUrl: string, forceNew?: boolean): Promise<HandshakeResult>;

    /**
     * Encrypt data using AES-256-GCM
     * 
     * @param data - Plain text data to encrypt
     * @returns Promise with encrypted data (base64)
     * 
     * @example
     * ```typescript
     * const encrypted = await QuantShield.encryptData('Hello World');
     * ```
     */
    encryptData(data: string): Promise<string>;

    /**
     * Decrypt data using AES-256-GCM
     * 
     * @param cipher - Encrypted data (base64)
     * @returns Promise with decrypted response object
     * 
     * @example
     * ```typescript
     * const decrypted = await QuantShield.decryptData(encryptedData);
     * console.log(decrypted.body);
     * ```
     */
    decryptData(cipher: string): Promise<DecryptedResponse>;

    /**
     * Apply XMLHttpRequest patching (also intercepts Axios)
     * 
     * @param proxyUrl - URL of decrypt-and-forward endpoint
     * @param allowedDomains - Optional array of domains to intercept
     * 
     * @example
     * ```typescript
     * QuantShield.applyPatchXHR('https://your-proxy.com/decrypt-and-forward', [
     *   'api.example.com'
     * ]);
     * ```
     */
    applyPatchXHR(proxyUrl: string, allowedDomains?: string[]): void;

    /**
     * Apply fetch() patching for automatic encryption
     * 
     * @param proxyUrl - URL of decrypt-and-forward endpoint
     * @param allowedDomains - Optional array of domains to intercept
     * 
     * @example
     * ```typescript
     * QuantShield.applyPatchFetch('https://your-proxy.com/decrypt-and-forward', [
     *   'api.example.com'
     * ]);
     * ```
     */
    applyPatchFetch(proxyUrl: string, allowedDomains?: string[]): void;

    /**
     * Enable automatic key rotation
     * 
     * Performs new handshake at specified interval to rotate encryption keys.
     * 
     * @param intervalMinutes - Interval in minutes (default: 10)
     * 
     * @example
     * ```typescript
     * // Refresh keys every 10 minutes
     * QuantShield.enableAutoRefresh(10);
     * ```
     */
    enableAutoRefresh(intervalMinutes?: number): void;

    /**
     * Disable automatic key rotation
     * 
     * @example
     * ```typescript
     * QuantShield.disableAutoRefresh();
     * ```
     */
    disableAutoRefresh(): void;
  }

  const QuantShield: QuantShieldAPI;
  export default QuantShield;
}