Using SafeQuard in React Native App
=========================================

This section explains how the SafeQuard post-quantum encryption system (Kyber ML-KEM-768 + AES-256) is integrated into a cross-platform mobile application built with **React Native**.

The module can be easily integrated into any React Native application by embedding the ``SafeQuardWebView.html`` file within a WebView.
Encryption functions are called by passing data to the WebView using the `postMessage` interface, enabling secure client-side encryption before sending any data to the backend server.

.. Files
.. -------------
.. These are the files that are deployed as part of the SafeQuard solution.
.. The directory structure of the file server is as follows::

..    assets/html/
..    ├── License
..    └── SafeQuardWebView.html

.. - The ``License`` contains the terms and conditions for using the SafeQuard solution.

.. - The ``SafeQuardWebView.html`` is the HTML file embedded in the React Native WebView. It loads the ``SafeQuard.js`` and ``SafeQuard.wasm`` remotely, and exposes encryption functionality to the mobile app via `postMessage`.

.. - The ``SafeQuard.js`` **(fetched remotely)** is the JavaScript wrapper that interfaces with the WASM module.

.. - The ``SafeQuard.wasm`` **(fetched remotely)** is the WebAssembly file that powers the core functionality of SafeQuard.


Step 1: Embed the SafeQuard WebView
------------------------------------------

In your React Native project, the SafeQuard module is embedded using a local HTML file loaded into a WebView:

::

   assets/html/SafeQuardWebView.html

Replace `https://<SafeQuard-app-service-url>`` with the actual URL of the file server hosting the `SafeQuard.js` and `SafeQuard.wasm`,
refer to the :ref:`sq-files` section for more details.

Inside the file, the following script loads the module:

.. code-block:: javascript

   const [jsTxt, wasmBin] = await Promise.all([
       fetch('https://<SafeQuard-app-service-url>/SafeQuard.js').then(r => r.text()),
       fetch('https://<SafeQuard-app-service-url>/SafeQuard.wasm').then(r => r.arrayBuffer())
   ]);

Step 2: Sending Data to WebView for Encryption
---------------------------------------------------------------

The React Native component (e.g. ``Encrypt.tsx``) sends messages to the WebView to initiate encryption:

.. code-block:: typescript

   webViewRef.current?.postMessage(JSON.stringify({
     action: 'encrypt_text',
     text: 'sensitive data to be sent'
   }));

This message is handled in `SafeQuardWebView.html` via an event listener:

.. code-block:: html

   <script>
      const Module = await SafeQuard({ wasmBinary: new Uint8Array(wasmBin) });
      window.ReactNativeWebView.postMessage(JSON.stringify({ type: 'ready' }));

      window.addEventListener('message', async (e) => {
         const msg = JSON.parse(e.data);
         if (msg.action === 'encrypt_text') {
            // Ensure the SafeQuard module is loaded
            const base64_text = btoa(unescape(encodeURIComponent(msg.text)));

            const result = Module.ccall(
               'pQCee_SafeQuard_enc',
               'string',
               ['string', 'string'],
               [base64_text, publicKey]
            );
         }
      });
   </script>

The encrypted data (result) is then securely transmitted to the backend (server.js), ensuring that even if intercepted, it remains unintelligible to hackers. The server decrypts the ciphertext upon receipt.

User and System Flow
---------------------

.. image:: ./images/safequard-reactnative-architecture.png
   :alt: Encryption flow diagram
   :width: 100%
   :align: center


Platform Notes
--------------

The React Native app is compatible with both **Android** and **iOS**, using platform-specific message handling inside the WebView:

- **Android**: WebView listens using ``document.addEventListener('message')``
- **iOS**: WebView requires ``window.addEventListener('message')``

To support both, both listeners are used.

Troubleshooting (For Developers)
------------------------------------

- Make sure both mobile and PC are on the **same Wi-Fi network**
- If Expo Go cannot connect, try ``--tunnel`` instead of LAN mode.
- Ensure your firewall allows port ``8000`` for backend.