Proxy Server Interoperability (#66)

Bumps version to v2.0.3

Allows for clients to be configured in 2 operating modes: direct and
proxy mode.

Proxy mode allows proxying calls through a proxy server and does not
require holding API key information in the React Native App.

Direct mode uses API key information stored in the React Native app to
make direct calls to the WaaS backend.

Co-authored-by: Jayasudha Jayakumaran <[email protected]>

README.md

@@ -63,6 +63,21 @@ This repository provides an example app that demonstrates how the APIs should be
 > To run the example app, populate, or replace, this file with the Cloud API Key file provided to you
 > by Coinbase.
 
+### Running in Proxy-Mode (recommended)
+
+To run the example app using `proxy-mode`:
+
+1. Ensure the proxy server is correctly set up and active at the designated endpoint. The default endpoint is `localhost:8091`.
+2. If your proxy server endpoint differs from the default, update the `proxyUrl` in the `config.json` file accordingly.
+3. On app startup, choose `Proxy Mode` from the Mode Selection screen.
+
+### Running in Direct-Mode (not recommended)
+
+To run the example app using `direct-mode`:
+
+1. Populate the `.coinbase_cloud_api_key.json` file with your personal API credentials.
+2. On app startup, select `Direct Mode` from the Mode Selection screen.
+
 ### iOS
 Ensure you have XCode open and run the following from the root directory of the repository:
 
@@ -103,6 +118,8 @@ yarn example start # Start the Metro server
 yarn example android # Build and start the app on Android emulator
 ```
 
+By following the above steps, you should be able to run the example app either in proxy-mode or direct-mode based on your preference and setup.
+
 ## Recommended Architecture
 
 Broadly speaking, there are two possible approaches to using the WaaS SDK:
@@ -132,6 +149,25 @@ The methods from the WaaS SDK which are _required_ to be used for participation
 3. `getRegistrationData`
 4. `computeMPCOperation`
 
+## Proxy-Mode vs. Direct-Mode
+
+Users can switch between two distinct operating modes: `proxy-mode` and `direct-mode`.
+
+### Proxy-Mode (recommended)
+
+**Proxy-mode** allows the application to connect to the Coinbase WaaS API through a proxy server. The primary features of this mode include:
+
+- Initiate the SDK without needing the Coinbase Cloud API key details in the app itself. Communication will be authenticated during Proxy-Server <> WaaS API.
+- The SDK, by default, points to a proxy server endpoint at `localhost:8091`. Update this `proxyUrl` in the `config.json` file.
+- Cloud credentials are stored in the proxy server, eliminating the need to have them on the application side.
+
+### Direct-Mode (not recommended)
+
+**Direct-mode** enables the app to connect directly to the Coinbase WaaS API, bypassing the need for a proxy server. Key aspects of this mode are:
+
+- The app communicates directly with the Coinbase WaaS API, with no involvement of a proxy server.
+- Users must provide the API Key and private key for communication, retrieved from the `.coinbase_cloud_api_key.json` file.
+
 # Native Waas SDK
 
 We expose a Java 8+, `java.util.concurrent.Future`-based SDK for use with Java/Kotlin. An example

android-native/src/main/java/com/coinbase/waassdk/MPCKeyService.java

@@ -27,23 +27,36 @@
  */
 public class MPCKeyService {
 
-  // The URL of the MPCKeyService.
-  public static final String mpcKeyServiceUrl = "https://api.developer.coinbase.com/waas/mpc_keys";
-
+  // The URL of the MPCKeyService when running in "direct mode".
+  public static final String mpcKeyServiceWaaSUrl = "https://api.developer.coinbase.com/waas/mpc_keys";
   // The handle to the Go MPCKeyService client.
   com.waassdkinternal.v1.MPCKeyService keyClient;
 
   ExecutorService executor;
 
   /**
-   * Initializes the MPCKeyService, for a given apiKey / privateKey.
+   * Initializes the MPCKeyService with the given Cloud API Key parameters or proxy URL.
+   * Utilizes `proxyUrl` and operates in insecure mode if either `apiKeyName` or `privateKey` is missing.
+   * Uses direct WaaS URL with the API keys if both are provided.
    * NOTE: You should almost never include this statically in your code, and you should
-   * call our endpoints via a proxy service. This API will change in the future
-   * to accommodate proxy services better.
+   *       call our endpoints via a proxy service. This API will change in the future
+   *       to accommodate proxy services better.
    */
-  public MPCKeyService(String apiKeyName, String privateKey, ExecutorService executor) throws WaasException {
+  public MPCKeyService(String apiKeyName, String privateKey, String proxyUrl, ExecutorService executor) throws WaasException {
+    Bool insecure;
+
+    String mpcKeyServiceUrl;
+
+    if (apiKeyName == "" && privateKey == "") {
+      mpcKeyServiceUrl = proxyUrl;
+      insecure = true;
+    } else {
+      mpcKeyServiceUrl = mpcKeyServiceWaaSUrl;
+      insecure = false;
+    }
+
     try {
-      keyClient = newMPCKeyService(mpcKeyServiceUrl, apiKeyName, privateKey);
+      keyClient = newMPCKeyService(mpcKeyServiceUrl, apiKeyName, privateKey, insecure);
       this.executor = executor;
     } catch (Exception e) {
       throw new WaasException("Error initializing mpckey-service: ", e.getMessage());

android-native/src/main/java/com/coinbase/waassdk/MPCWalletService.java

@@ -17,7 +17,8 @@
  * Methods for creating and managing MPC wallets with Coinbase.
  */
 public class MPCWalletService {
-  public static final String mpcWalletServiceUrl = "https://api.developer.coinbase.com/waas/mpc_wallets";
+  // The URL of the MPCWalletService when running in "direct mode".
+  public static final String mpcWalletServiceWaaSUrl = "https://api.developer.coinbase.com/waas/mpc_wallets";
 
   com.waassdkinternal.v1.MPCWalletService walletsClient;
 
@@ -27,15 +28,27 @@ private <T> Future<T> call(Callable<T> callable) {
     return executor.submit(callable);
   }
 
-
   /**
-   * Initializes the MPCWalletService with the given Cloud API Key parameters.
-   * NOTE: You should almost-never include these credentials in your app, and instead
-   * delegate to a proxy server to perform these calls.
+   * Initializes the MPCWalletService with the given Cloud API Key parameters or proxy URL.
+   * Utilizes `proxyUrl` and operates in insecure mode if either `apiKeyName` or `privateKey` is missing.
+   * NOTE: You should almost never include these credentials in your app, and instead
+   *       delegate to a proxy server to perform these calls.
    */
-  public MPCWalletService(String apiKeyName, String privateKey, ExecutorService executor) throws WaasException {
+  public MPCWalletService(String apiKeyName, String privateKey, String proxyUrl, ExecutorService executor) throws WaasException {
+    Bool insecure;
+
+    String mpcWalletServiceUrl;
+
+    if (apiKeyName == "" && privateKey == "") {
+      mpcWalletServiceUrl = proxyUrl;
+      insecure = true;
+    } else {
+      mpcWalletServiceUrl = mpcWalletServiceWaaSUrl;
+      insecure = false;
+    }
+
     try {
-      walletsClient = newMPCWalletService(mpcWalletServiceUrl, apiKeyName, privateKey);
+      walletsClient = newMPCWalletService(mpcWalletServiceUrl, apiKeyName, privateKey, insecure);
       this.executor = executor;
     } catch (Exception e) {
       throw new WaasException("initialize MPC wallet service failed : ", e.getMessage());

android-native/src/main/java/com/coinbase/waassdk/PoolService.java

@@ -12,21 +12,35 @@
  * A pool represents a group of related wallets.
  */
 public class PoolService {
-  // The URL of the PoolService.
-  public static String poolServiceUrl = "https://api.developer.coinbase.com/waas/pools";
-
+  // The URL of the PoolService when running in "direct mode".
+  public static final String poolServiceWaaSUrl = "https://api.developer.coinbase.com/waas/pools";
   // The handle to the Go PoolService client.
   com.waassdkinternal.v1.PoolService poolClient;
   ExecutorService executor;
 
   /**
-   * Initializes the PoolService with the given Cloud API Key parameters. Resolves with the string "success" on success;
-   * rejects with an error otherwise.
+   * Initializes the PoolService with the given Cloud API Key parameters or proxy URL.
+   * Utilizes `proxyUrl` and operates in insecure mode if either `apiKeyName` or `privateKey` is missing.
+   * Uses direct WaaS URL with the API keys if both are provided.
+   * Resolves with the string "success" on success; rejects with an error otherwise.
    */
-  public PoolService(String apiKeyName, String privateKey, ExecutorService executor) throws WaasException {
+  public PoolService(String apiKeyName, String privateKey, String proxyUrl, ExecutorService executor) throws WaasException {
     this.executor = executor;
+
+    Bool insecure;
+
+    String poolServiceUrl;
+
+    if (apiKeyName == "" && privateKey == "") {
+      poolServiceUrl = proxyUrl;
+      insecure = true;
+    } else {
+      poolServiceUrl = poolServiceWaaSUrl;
+      insecure = false;
+    }
+
     try {
-      poolClient = newPoolService(poolServiceUrl, apiKeyName, privateKey);
+      poolClient = newPoolService(poolServiceUrl, apiKeyName, privateKey, insecure);
     } catch (Exception e) {
       throw new WaasException("initialize pool failed : ", e.getMessage());
     }

android/gradle.properties

@@ -3,7 +3,7 @@ WaasSdkReactNative_minSdkVersion=21
 WaasSdkReactNative_targetSdkVersion=31
 WaasSdkReactNative_compileSdkVersion=31
 WaasSdkReactNative_ndkversion=21.4.7075529
-WaasSdkReactNative_goInternalSdkVersion=0.1.1
+WaasSdkReactNative_goInternalSdkVersion=0.1.8
 WaasSdkReactNative_mpcSdkVersion=0.0.2
 android.useAndroidX=true
 kotlinCompilerVersion=1.8.0

example/src/App.tsx

@@ -1,5 +1,4 @@
-import * as React from 'react';
-
+import React, { useState, useEffect, useContext } from 'react';
 import { NavigationContainer } from '@react-navigation/native';
 import { createNativeStackNavigator } from '@react-navigation/native-stack';
 import { HomeScreen } from './screens/HomeScreen';
@@ -11,25 +10,42 @@ import { MPCKeyExportDemo } from './screens/MPCKeyExportDemo';
 import AppContext from './components/AppContext';
 import { DeviceBackupDemo } from './screens/DeviceBackupDemo';
 import { DeviceAdditionDemo } from './screens/DeviceAdditionDemo';
+import { ModeSelectionScreen } from './screens/ModeSelectionScreen';
+import { ModeContext } from './utils/ModeProvider';
+import { ModeProvider } from './utils/ModeProvider';
 
 /** The navigation stack. */
 const Stack = createNativeStackNavigator();
 
-const cloudAPIKey = require('./.coinbase_cloud_api_key.json');
+function SetupApp() {
+  const [apiKeyData, setApiKeyData] = useState<any>({});
+  const [proxyUrlData, setProxyUrlData] = useState<string>('');
+  const { selectedMode } = useContext(ModeContext);
 
-export default function App() {
-  const apiKeyName = cloudAPIKey.name;
-  const privateKey = cloudAPIKey.privateKey;
+  useEffect(() => {
+    if (selectedMode === 'direct-mode') {
+      const cloudAPIKey = require('./.coinbase_cloud_api_key.json');
+
+      setApiKeyData(cloudAPIKey);
+    } else {
+      const config = require('./config.json');
 
-  const userCredentials = {
-    apiKeyName,
-    privateKey,
-  };
+      setProxyUrlData(config.proxyUrl);
+    }
+  }, [selectedMode]);
+
+  const apiKeyName = apiKeyData.name || '';
+  const privateKey = apiKeyData.privateKey || '';
+  const proxyUrl = proxyUrlData || '';
 
   return (
-    <AppContext.Provider value={userCredentials}>
+    <AppContext.Provider value={{ apiKeyName, privateKey, proxyUrl }}>
       <NavigationContainer>
-        <Stack.Navigator>
+        <Stack.Navigator initialRouteName="ModeSelectionScreen">
+          <Stack.Screen
+            name="ModeSelectionScreen"
+            component={ModeSelectionScreen}
+          />
           <Stack.Screen name="Home" component={HomeScreen} />
           <Stack.Screen name="PoolServiceDemo" component={PoolServiceDemo} />
           <Stack.Screen
@@ -52,3 +68,11 @@ export default function App() {
     </AppContext.Provider>
   );
 }
+
+export default function App() {
+  return (
+    <ModeProvider>
+      <SetupApp />
+    </ModeProvider>
+  );
+}

example/src/components/AppContext.tsx

@@ -4,6 +4,7 @@ import React from 'react';
 export type Context = {
   apiKeyName?: string;
   privateKey?: string;
+  proxyUrl?: string;
 };
 
 const AppContext = React.createContext<Context>({});

example/src/config.json

@@ -0,0 +1,3 @@
+{
+    "proxyUrl": "http://localhost:8091"
+}

example/src/constants.ts

@@ -0,0 +1,4 @@
+// The operating mode where the app connects directly to the WaaS API.
+export const directMode: string = 'direct-mode';
+// The operating mode where the app connects to the WaaS API via a proxy server.
+export const proxyMode: string = 'proxy-mode';

example/src/screens/DeviceAdditionDemo.tsx

@@ -17,6 +17,8 @@ import { InputText } from '../components/InputText';
 import { PageTitle } from '../components/PageTitle';
 import AppContext from '../components/AppContext';
 import { Note } from '../components/Note';
+import { ModeContext } from '../utils/ModeProvider';
+import { directMode, proxyMode } from '../constants';
 
 export const DeviceAdditionDemo = () => {
   const [deviceGroupName, setDeviceGroupName] = React.useState<string>('');
@@ -36,29 +38,40 @@ export const DeviceAdditionDemo = () => {
   const [showStep6, setShowStep6] = React.useState<boolean>();
   const [showError, setShowError] = React.useState<boolean>();
 
-  const credentials = React.useContext(AppContext);
-  const apiKeyName = credentials.apiKeyName as string;
-  const privateKey = credentials.privateKey as string;
+  const { selectedMode } = React.useContext(ModeContext);
+  const {
+    apiKeyName: apiKeyName,
+    privateKey: privateKey,
+    proxyUrl: proxyUrl,
+  } = React.useContext(AppContext) as {
+    apiKeyName: string;
+    privateKey: string;
+    proxyUrl: string;
+  };
 
   //  Runs the DeviceAdditionDemo.
   React.useEffect(
     () => {
       let demoFn = async function () {
+        if (!showStep2 || showStep6 || deviceGroupName) {
+          return;
+        }
+
         if (
-          deviceGroupName === '' ||
-          apiKeyName === '' ||
-          privateKey === '' ||
-          !showStep2 ||
-          showStep6
+          selectedMode === directMode &&
+          (apiKeyName === '' || privateKey === '')
         ) {
           return;
         }
 
         try {
+          const apiKey = selectedMode === proxyMode ? '' : apiKeyName;
+          const privKey = selectedMode === proxyMode ? '' : privateKey;
+
           // Initialize the MPCKeyService and MPCSdk.
           await initMPCSdk(true);
-          await initMPCKeyService(apiKeyName, privateKey);
-          await initMPCWalletService(apiKeyName, privateKey);
+          await initMPCKeyService(apiKey, privKey, proxyUrl);
+          await initMPCWalletService(apiKey, privKey, proxyUrl);
 
           if (!showStep5) {
             const operationName = await addDevice(deviceGroupName, deviceName);
@@ -99,10 +112,12 @@ export const DeviceAdditionDemo = () => {
       deviceGroupName,
       apiKeyName,
       privateKey,
+      proxyUrl,
       showStep2,
       deviceName,
       deviceBackup,
       passcode,
+      selectedMode,
     ]
   );