react-native-mfa-trustbuilder

Trustbuilder MFA SDK for React Native. Provides multi-factor authentication capabilities including activation, OTP generation, biometric authentication, push notifications, and transaction sealing.

Installation

npm install react-native-mfa-trustbuilder

iOS

cd ios && pod install

Android

No additional steps required.

Usage

import { trustbuilder, TrustbuilderError } from 'react-native-mfa-trustbuilder';

// Initialize (call once at app startup)
const result = trustbuilder.initialize({
  macId: 'your_maccess_id',
  server: 'https://www.myinwebo.com',
  hostVersion: 'my-app-1.0.0',
});

// Restore saved state
const storedData = trustbuilder.getStorageData();
if (storedData) {
  trustbuilder.setStorageData(storedData);
}

// Check activation status
if (trustbuilder.isActivated()) {
  // Generate online OTP
  const { otp, remainingTime } = await trustbuilder.generateOnlineOtp('1234');
}

API Reference

Initialization

initialize(config: InitConfig): InitResult

Initialize the Trustbuilder SDK.

trustbuilder.initialize({
  macId: 'your_maccess_id', // Required
  server: 'https://www.myinwebo.com', // Default
  hostVersion: 'my-app-1.0.0', // Default: 'react-native-mfa-trustbuilder-0.1.0'
  timeout: 60000, // Default: 60000ms
  lang: 'en', // 'en' | 'fr', Default: 'en'
});

Activation

activationStart(code: string): Promise<void>

Start the device activation process.

activationFinalize(code: string, pin: string, name: string): Promise<void>

Finalize device activation.

activate(code: string, pin: string, name: string): Promise<void>

Convenience method that calls both start and finalize.

Unlock / Reset

reset(code: string, pin: string): Promise<void>

Unlock a blocked device with an unlock code.

Synchronization

synchronize(pin: string): Promise<void>

Synchronize device state with Trustbuilder servers.

PIN Management

updatePin(newPin: string, currentPin: string): Promise<void>

Update the user's PIN code.

Biometrics

registerBiokey(biokey: string, pin: string): Promise<void>

Register a biometric key.

resetBiokeys(pin: string): Promise<void>

Reset all registered biometric keys.

OTP Generation

generateOnlineOtp(pin: string, serviceIndex?: number, keyType?: KeyType): Promise<OtpResult>

Generate an OTP via server call.

generateOfflineOtp(pin: string, serviceId?: number): Promise<OtpResult>

Generate an OTP locally without network.

Push Notifications

registerForPush(pushId: string): Promise<void>

Register device for push notifications.

getPushInfo(): PushInfo | null

Check for pending push notification.

onPushReceived(listener: (pushInfo: PushInfo) => void): () => void

Subscribe to push notification events.

Sealing

generateOnlineSeal(pin: string, sealData: string, serviceIndex?: number, keyType?: KeyType): Promise<SealResult>

Generate an online seal.

generateOfflineSeal(pin: string, sealData: string, serviceId?: number): Promise<SealResult>

Generate an offline seal.

Utility

isActivated(): boolean

Check if device is activated.

isBlocked(): boolean

Check if device is blocked.

getServiceInfo(index?: number): ServiceInfo

Get service information.

getVersionInfo(): VersionInfo

Get SDK version information.

saveStorageIfNeeded(): void

Save internal state if it has changed. Call after each operation.

Error Handling

All methods throw TrustbuilderError on failure:

try {
  await trustbuilder.generateOnlineOtp('1234');
} catch (error) {
  if (error instanceof TrustbuilderError) {
    console.log(error.code); // Numeric error code
    console.log(error.codeName); // e.g., 'NETWORK', 'CODE', 'ACCESS'
    console.log(error.message); // Human-readable message
  }
}

Error Codes

| Code | Name | Description | | ---- | -------------- | ---------------------------------- | | 0 | OK | No error | | 1 | NETWORK | Network or server unreachable | | 2 | CODE | Activation code is incorrect | | 3 | SN | Syntax error | | 4 | ACCESS | Access refused | | 5 | VERSION | Version error | | 7 | BLOCKED | Account is blocked | | 14 | FORBIDDEN | Forbidden operation | | 15 | PINREFUSED | Bad PIN format | | 16 | TIMEOUT | Timeout expired | | 26 | BIOKEY | Device locked due to biokey errors | | 27 | DESYNCHRONIZED | Device desynchronized | | 999 | OTHER | Unknown error |

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT