# react-native-opaque
React Native client for the OPAQUE Protocol
## Installation
```sh
npm install react-native-opaque
```
## Usage
```js
import * as opaque from 'react-native-opaque';
const { clientRegistration, registrationRequest } =
opaque.clientRegistrationStart('hunter2');
// ...
```
## Usage with React Native Web
Since on web the package uses Web Assembly under the hood, it needs to be loaded asynchronously. To offer the same API the module is loaded internally, but in addition the API offers a `ready` Promise that will resolve once the module is loaded and ready to be used.
```ts
import * as opaque from 'react-native-opaque';
opaque.ready.then(() => {
const { clientRegistration, registrationRequest } =
opaque.clientRegistrationStart('hunter2');
// ...
});
```
The most convenient way to use this is to have loading page that waits for the `ready` Promise to resolve before rendering the actual app.
For example:
```tsx
export default function LoadingApp() {
const [opaqueModuleStatus, setOpaqueModuleStatus] = React.useState<
'loading' | 'failed' | 'loaded'
>('loading');
React.useEffect(() => {
async function waitForOpaque() {
try {
await opaque.ready;
setOpaqueModuleStatus('loaded');
} catch (e) {
console.warn(e);
setOpaqueModuleStatus('failed');
}
}
waitForOpaque();
}, []);
if (opaqueModuleStatus === 'loading') return null;
if (opaqueModuleStatus === 'failed')
return Failed to load resources. Please reload the app.;
return ;
}
```
Note: The `ready` Promise resolves right away on the native side.
## Build Setup
Directory overview:
```
/
cpp/
opaque-rust.cpp # generated from cxxbridge
opaque-rust.h
react-native-opaque.cpp # JSI bindings for the opaque_rust C++ interface
react-native-opaque.h
rust/
src/lib.rs # Rust source
build-android.{sh,bat} # Build library for given android target
build-all.{sh,bat} # Build all targets (only android on windows)
gen-cxx.{sh,bat} # Generate cxx source
android/
CMakeLists.txt # the build config where we set up the C++ source and link with the Rust lib
cpp-adapter.cpp # defines the JNI "initialize" function which installs opaque JSI functions
react-native-opaque.podspec # build config for iOS to include the C++ and link with Rust lib
```
### Rust Build
```bash
cd rust
cargo install cxxbridge-cmd # (if not installed already)
rustup target add x86_64-apple-ios aarch64-apple-ios aarch64-apple-ios-sim # (if on macOS and not installed already)
rustup target add i686-linux-android x86_64-linux-android aarch64-linux-android arm-linux-androideabi # (if not installed already)
./build-all.sh # (inside the rust directory)
```
To pass additional arguments to cargo you can set the `EXTRA_ARGS` env variable.
For example, to do a release build with p256 feature:
```bash
EXTRA_ARGS="--feature p256" ./build-all.sh
```
We use the cxx crate to generate the glue code to expose a C++ interface from rust.
The cxx crate itself includes a C++ build step in its own build script.
Unfortunately cross-compilation for Android requires special care to use the NDK toolchain and it is currently not possible to set up target specific environment variables in a cargo config.
Therefore the rust project needs to be built with a separate build script `build-all.sh` (or `build-all.bat` on Windows).
Since the C++ code generated by cxx further needs to be included by our XCode or Gradle+CMake build we use the `rust/gen-cxx.sh` script to invoke the `cxxbridge` command to generate the C++ source.
This requires the `cxxbridge-cmd` cargo package to be installed (`cargo install cxxbridge-cmd`).
Note that the `gen-cxx` script will be run at the end of `build-all` so you don't need to run it manually.
### iOS Build
The podspec uses the `pod_target_xcconfig` setting to set up appropriate `LIBRARY_SEARCH_PATHS` and `LIBTOOLFLAGS` to link with the rust library and includes the `ios/` and `cpp/` source in the build.
After the rust library is built you can run
```bash
yarn example ios
```
as usual in the project root to build and run the iOS example app.
### Android Build
The `CMakeLists.txt` includes the `cpp/` source and links with the appropriate rust library target depending on the target arch.
After the rust library is built you can run
```bash
# list our emulators e.g. emulator -list-avds
# start the emulator e.g. emulator @Pixel_3a_API_33_arm64-v8a
yarn example android
```
as usual in the project root to build and run the Android example app.
### Module initialization
On both iOS and Android we define a react native module with a single `install` function (`ios/Opaque.mm` and `android/src/main/java/com/opaque/OpaqueModule.java`).
This install function is called when the module is imported on the JavaScript side which then calls the `installOpaque` function (in `cpp/react-native-opaque.cpp`) to register the opaque JSI functions.
On Android we need the additional `cpp-adapter.cpp` which defines a JNI function `initialize` which can be called from the Java side to indirectly call the `installOpaque` function on the native C++ side.
## Contributing
See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
## License
MIT
---
Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)
## Acknowledgement
This project was supported by the [Netidee funding campaign](https://www.netidee.at/).
