Using SafeQuard in Mobile 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.

The module can be easily integrated into any mobile 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

   SafeQuard-demo/
   └── server.js

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

- The ``SafeQuardWebView.html`` is the HTML file embedded in the 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.

- The ``server.js`` is the backend server that handles incoming encrypted data from the mobile app, decrypts and displays on the web interface.


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

In your mobile app, the SafeQuard module is embedded using a local HTML file loaded into a WebView:

::

   assets/html/SafeQuardWebView.html

Within this file, the SafeQuard module are fetched from remote to ensure latest content:

.. code-block:: javascript

       'https://<SafeQuard-app-service-url>/SafeQuard.js'
       'https://<SafeQuard-app-service-url>/SafeQuard.wasm'

**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.

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

App client (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/sq_mobile.png
   :alt: Encryption flow diagram
   :width: 100%
   :align: center


Notes on Other Frameworks
--------------

The SafeQuard WebView architecture is designed to be modular and portable, allowing it to be integrated into other mobile development frameworks beyond React Native.

- **Flutter**
  SafeQuard can be loaded via the `webview_flutter` package.

- **iOS Native (Swift)**
  Using `WKWebView`, you can load the local `SafeQuardWebView.html` file and communicate through `WKScriptMessageHandler`.

- **Android Native (Java/Kotlin)**
  Using Android's `WebView`, you can include the HTML file in the `assets/` folder and load it with `file:///android_asset/`.


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.