Session Storage

This guide covers securely storing and restoring Privacy Boost sessions in React Native, expanding on the persistence options in Key Management.

Storage Options

React Native offers several storage options with different security trade-offs:

Storage	Security	Use when
AsyncStorage	Low (unencrypted)	Development only
react-native-keychain	High (OS keychain)	Production apps

There are two ways to use the keychain. The SDK can own the vault itself through a KeychainDelegate you implement in JavaScript, which is the path described next, or the app can export the session and store it with its own code, which the rest of this guide covers.

SDK-Managed Persistence

Implement KeychainDelegate, register it with registerKeychainDelegate before constructing the SDK, and select persistenceStorage: StorageBackend.OsKeychain plus an unlock method. The delegate stores raw bytes under a key; this one backs it with react-native-keychain, base64-encoding the value because that API stores strings, and keeps one keychain service per key so a biometric-gated item never shares an entry with an unprotected one:

import * as Keychain from 'react-native-keychain';
import { Buffer } from 'buffer';
import {
  registerKeychainDelegate,
  hasKeychainDelegate,
  type KeychainDelegate,
} from '@sunnyside-io/privacy-boost-react-native';

const SERVICE_PREFIX = 'com.yourapp.privacyboost.';

export async function setupPrivacyBoostKeychain(): Promise<void> {
  if (hasKeychainDelegate()) return;
  const biometry = await Keychain.getSupportedBiometryType();

  const delegate: KeychainDelegate = {
    async store(key, value, requireBiometry) {
      await Keychain.setGenericPassword(key, Buffer.from(value).toString('base64'), {
        service: SERVICE_PREFIX + key,
        accessible: Keychain.ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
        ...(requireBiometry
          ? { accessControl: Keychain.ACCESS_CONTROL.BIOMETRY_CURRENT_SET }
          : {}),
      });
    },
    async load(key) {
      const item = await Keychain.getGenericPassword({ service: SERVICE_PREFIX + key });
      if (!item) return undefined;
      const bytes = Buffer.from(item.password, 'base64');
      return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
    },
    async remove(key) {
      await Keychain.resetGenericPassword({ service: SERVICE_PREFIX + key });
    },
    async contains(key) {
      return Keychain.hasGenericPassword({ service: SERVICE_PREFIX + key });
    },
    isAvailable: () => true,
    supportsBiometry: () => biometry !== null,
  };

  registerKeychainDelegate(delegate);
}

import {
  PrivacyBoost,
  PrivacyBoostConfig,
  StorageBackend,
  UnlockMethod,
} from '@sunnyside-io/privacy-boost-react-native';

await setupPrivacyBoostKeychain();

const sdk = new PrivacyBoost(PrivacyBoostConfig.create({
  serverUrl: 'https://indexer.example.com',
  chainId: undefined,
  shieldContractAddress: undefined,
  wethContractAddress: undefined,
  teePublicKey: undefined,
  appId: 'my-app',
  persistenceStorage: StorageBackend.OsKeychain,
  persistenceUnlock: UnlockMethod.Pin,
}));

registerKeychainDelegate takes an optional second argument that namespaces the vault items; omit it and the SDK uses its own name. The delegate above already prefixes its own service per key, so it does not need one. The registration is process-wide: do it before the first PrivacyBoost whose config selects OsKeychain, and note that a later call replaces the delegate for every instance. Construction throws SdkError.ConfigError naming register_keychain_delegate when no delegate is registered; hasKeychainDelegate() tells you whether one is. LocalStorage and IndexedDb are browser backends and are rejected on React Native, as is Passkey unlock.

Unlock methods

`persistenceUnlock`	On the next launch
`Pin`, `Password`	`authenticate` returns `CredentialRequired`; collect the credential and call `submitCredential`.
`Biometric`	The SDK calls `store` with `requireBiometry: true`, so the delegate above writes the vault behind the OS biometric prompt and reading it shows Face ID, Touch ID, or the fingerprint prompt. There is no credential challenge: `authenticate` asks the wallet for one signature to derive the vault key and returns `Authenticated`.
`None`	One wallet signature, then `Authenticated`.

Unlocking on the next launch

With Pin or Password, the first launch returns CredentialRequired with challenge.action === CredentialAction.Setup, where the user chooses the credential, and every later launch returns it with CredentialAction.Unlock. submitCredential completes the login either way and can be retried after a wrong credential without calling authenticate again:

import {
  KeySource,
  CredentialAction,
  type LoginResult,
} from '@sunnyside-io/privacy-boost-react-native';

async function signIn(): Promise<LoginResult> {
  const result = await sdk.authenticate(
    walletDelegate,
    new KeySource.WalletDerived(),   // ignored once a vault exists
    undefined,
  );

  switch (result.tag) {
    case 'Authenticated':
      return result.loginResult;
    case 'CredentialRequired': {
      const pin = await promptForPin(result.challenge.action === CredentialAction.Setup);
      return sdk.submitCredential(pin, undefined);
    }
    default:
      // MnemonicGenerated, RecoveryRequired, AccountCreationRequired:
      // see Getting Started.
      throw new Error(`Unhandled auth result: ${result.tag}`);
  }
}

The vault survives logout() and lock(); call deleteVault() to erase it, for example when the user removes the account from the device. Auto-lock below wipes the decrypted keys on a timer and sends the user through this same unlock on the next key access.

Basic: AsyncStorage

The simplest approach, but AsyncStorage is unencrypted. Only suitable for development.

import AsyncStorage from '@react-native-async-storage/async-storage';
import { PrivacyBoost } from '@sunnyside-io/privacy-boost-react-native';

const SESSION_KEY = 'privacy_boost_session';

// Save session
async function saveSession(sdk: PrivacyBoost) {
  const session = sdk.exportSession();
  if (session) {
    await AsyncStorage.setItem(SESSION_KEY, JSON.stringify(session));
  }
}

// Restore session
async function restoreSession(sdk: PrivacyBoost): Promise<boolean> {
  const stored = await AsyncStorage.getItem(SESSION_KEY);
  if (!stored) return false;

  try {
    const session = JSON.parse(stored);
    return sdk.importSession(session);
  } catch {
    await AsyncStorage.removeItem(SESSION_KEY);
    return false;
  }
}

// Clear session
async function clearSession(sdk: PrivacyBoost) {
  sdk.logout();
  await AsyncStorage.removeItem(SESSION_KEY);
}

Recommended: react-native-keychain

For production apps, use react-native-keychain to store sessions in the platform’s secure storage (iOS Keychain / Android Keystore).

Install

npm install react-native-keychain
cd ios && pod install

Session Manager

import * as Keychain from 'react-native-keychain';
import { PrivacyBoost } from '@sunnyside-io/privacy-boost-react-native';

const SERVICE_NAME = 'com.yourapp.privacyboost';

async function saveSession(sdk: PrivacyBoost): Promise<void> {
  const session = sdk.exportSession();
  if (!session) return;

  await Keychain.setGenericPassword(
    'privacy-boost-session',
    JSON.stringify(session),
    { service: SERVICE_NAME }
  );
}

async function restoreSession(sdk: PrivacyBoost): Promise<boolean> {
  const credentials = await Keychain.getGenericPassword({ service: SERVICE_NAME });
  if (!credentials) return false;

  try {
    const session = JSON.parse(credentials.password);
    return sdk.importSession(session);
  } catch {
    await Keychain.resetGenericPassword({ service: SERVICE_NAME });
    return false;
  }
}

async function clearSession(sdk: PrivacyBoost): Promise<void> {
  sdk.logout();
  await Keychain.resetGenericPassword({ service: SERVICE_NAME });
}

With Biometric Protection

Add Face ID / fingerprint requirement to access stored sessions:

import * as Keychain from 'react-native-keychain';

async function saveSessionWithBiometrics(sdk: PrivacyBoost): Promise<void> {
  const session = sdk.exportSession();
  if (!session) return;

  await Keychain.setGenericPassword(
    'privacy-boost-session',
    JSON.stringify(session),
    {
      service: SERVICE_NAME,
      accessControl: Keychain.ACCESS_CONTROL.BIOMETRY_CURRENT_SET,
      accessible: Keychain.ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
    }
  );
}

async function restoreSessionWithBiometrics(sdk: PrivacyBoost): Promise<boolean> {
  try {
    const credentials = await Keychain.getGenericPassword({
      service: SERVICE_NAME,
      authenticationPrompt: {
        title: 'Unlock Privacy Boost',
        subtitle: 'Authenticate to access your private wallet',
      },
    });

    if (!credentials) return false;

    const session = JSON.parse(credentials.password);
    return sdk.importSession(session);
  } catch {
    // Biometric auth failed or was cancelled
    return false;
  }
}

Check Biometric Availability

import * as Keychain from 'react-native-keychain';

async function checkBiometrics(): Promise<string | null> {
  const biometryType = await Keychain.getSupportedBiometryType();
  // Returns: 'TouchID' | 'FaceID' | 'Fingerprint' | 'Iris' | null
  return biometryType;
}

Usage in a React Native Component

import React, { useEffect, useState } from 'react';
import { View, Text, Button, ActivityIndicator } from 'react-native';
import { KeySource } from '@sunnyside-io/privacy-boost-react-native';

function PrivacyWallet({ sdk }: { sdk: PrivacyBoost }) {
  const [loading, setLoading] = useState(true);
  const [authenticated, setAuthenticated] = useState(false);

  useEffect(() => {
    // Try restoring session on mount
    restoreSessionWithBiometrics(sdk)
      .then((restored) => {
        setAuthenticated(restored);
        setLoading(false);
      })
      .catch(() => setLoading(false));
  }, []);

  if (loading) return <ActivityIndicator />;

  if (!authenticated) {
    return (
      <View>
        <Text>Not logged in</Text>
        <Button
          title="Connect Wallet"
          onPress={async () => {
            const result = await sdk.authenticate(
              walletDelegate,
              new KeySource.WalletDerived(),
              undefined,
            );
            if (result.tag === 'Authenticated') {
              await saveSessionWithBiometrics(sdk);
              setAuthenticated(true);
            } else if (result.tag === 'MnemonicGenerated') {
              // First-time user: show the recovery phrase, then continue.
              await sdk.proceedAfterMnemonic(undefined);
              await saveSessionWithBiometrics(sdk);
              setAuthenticated(true);
            }
            // CredentialRequired / RecoveryRequired handled elsewhere.
          }}
        />
      </View>
    );
  }

  return (
    <View>
      <Text>Privacy Address: {sdk.getPrivacyAddress()}</Text>
      <Button
        title="Logout"
        onPress={async () => {
          await clearSession(sdk);
          setAuthenticated(false);
        }}
      />
    </View>
  );
}

Auto-lock

Auto-lock bounds how long the decrypted keys stay in memory. Two optional PrivacyBoostConfig fields drive it, both in seconds:

idleTtlSecs: how long the keys may go unused before the SDK wipes them.
absoluteTtlSecs: how long after an unlock the SDK wipes them, regardless of activity.

undefined or 0n disables the respective timer, and PrivacyBoostConfig.create() defaults both to undefined. The timers are checked lazily, on the next key access: once one has elapsed, that access zeroizes the resident keys and throws SdkError.NotAuthenticated. They bound key use rather than key residency, so a screen that needs the keys gone at a fixed time should call lock() from its own timer.

import { PrivacyBoost, PrivacyBoostConfig } from '@sunnyside-io/privacy-boost-react-native';

const sdk = new PrivacyBoost(PrivacyBoostConfig.create({
  serverUrl: 'https://indexer.example.com',
  chainId: undefined,
  shieldContractAddress: undefined,
  wethContractAddress: undefined,
  teePublicKey: undefined,
  appId: 'my-app',
  persistenceStorage: undefined,
  persistenceUnlock: undefined,
  idleTtlSecs: 300n,         // wipe keys after 5 minutes without use
  absoluteTtlSecs: 43_200n,  // and 12 hours after unlock, no matter what
}));

lock() does the same on demand. It zeroizes the key material and drops the session JWT but keeps any persisted vault, which makes it the right call when the app moves to the background:

import { AppState } from 'react-native';

AppState.addEventListener('change', (state) => {
  if (state === 'background') sdk.lock();
});

To unlock, call authenticate again. With a persisted vault the SDK reopens it instead of re-deriving keys; without one, authenticate derives them from the wallet signature as on first login. Compare clearSession(), which drops the JWT but leaves the keys in memory for a quick re-auth, and logout(), which ends the session entirely. Chain-context handles created with createChainContext share the resident keys, so auto-lock and lock() apply to them too, but each keeps its own JWT; call clearSession() on the handle to drop it.

iOS Configuration

Add Face ID usage description to ios/YourApp/Info.plist:

<key>NSFaceIDUsageDescription</key>
<string>Authenticate to access your Privacy Boost wallet</string>

Quickstart

Setup

SDKs

Session Storage

Session Storage

Storage Options

SDK-Managed Persistence

Unlock methods

Unlocking on the next launch

Basic: AsyncStorage

Recommended: react-native-keychain

Install

Session Manager

With Biometric Protection

Check Biometric Availability

Usage in a React Native Component

Auto-lock

iOS Configuration

Next Steps

​Session Storage

​Storage Options

​SDK-Managed Persistence

​Unlock methods

​Unlocking on the next launch

​Basic: AsyncStorage

​Recommended: react-native-keychain

​Install

​Session Manager

​With Biometric Protection

​Check Biometric Availability

​Usage in a React Native Component

​Auto-lock

​iOS Configuration

​Next Steps

Session Storage

Storage Options

SDK-Managed Persistence

Unlock methods

Unlocking on the next launch

Basic: AsyncStorage

Recommended: react-native-keychain

Install

Session Manager

With Biometric Protection

Check Biometric Availability

Usage in a React Native Component

Auto-lock

iOS Configuration

Next Steps