API Reference

Complete API documentation for @alphyn/react-native-sdk.

AlphynSDK

Main SDK class providing all security features. All methods are static.

import { AlphynSDK } from '@alphyn/react-native-sdk';

Core Methods

Method	Returns	Description
`initialize(config?)`	`Promise<void>`	Initializes the SDK with `scanInterval` and the optional per-platform debug hashes.
`isInitialized()`	`Promise<boolean>`	Returns whether the SDK is initialized and ready.
`getDeviceInfo()`	`Promise<DeviceInfo>`	Returns device ID, app hash, init state, and last scan date.
`getDeviceId()`	`Promise<string>`	Returns the persistent device identifier.
`getAppHash()`	`Promise<string>`	Returns the app integrity hash.
`getLastScanDate()`	`Promise<Date \| null>`	Returns the last scan date if available.
`signAction(userId, actionLabel, context, pin?, subject?)`	`Promise<ActionVerificationResult>`	Signs a high-risk action with an enrolled user’s hardware key. See MFA.

Initialization

initialize()

Initialize the SDK with configuration options.

static async initialize(config?: AlphynConfig): Promise<void>

Parameters:

Name	Type	Description
config	AlphynConfig	Optional configuration with `scanInterval`, `androidDebugHash` and `iosDebugHash`

Example:

await AlphynSDK.initialize({
  scanInterval: 45,
  androidDebugHash: __DEV__ ? 'YOUR_ANDROID_DEBUG_HASH' : undefined,
  iosDebugHash: __DEV__ ? 'YOUR_IOS_DEBUG_HASH' : undefined,
});

A React Native project registers as two separate apps on the portal, one per platform, each with its own hashes, so the debug hash is always platform-specific. There is no debugHash option; passing one has no effect. See Initialization.

Notes:

scanInterval is expressed in seconds and must be greater than 8.
initialize() is idempotent. Repeated calls succeed once the SDK is already initialized.

isInitialized()

Check if the SDK is initialized and ready.

static async isInitialized(): Promise<boolean>

Returns: true if SDK is initialized, false otherwise.

Example:

const ready = await AlphynSDK.isInitialized();
if (!ready) {
  console.log('SDK not initialized');
}

Device Information

getDeviceInfo()

Get comprehensive device and SDK status information.

static async getDeviceInfo(): Promise<DeviceInfo>

Returns: DeviceInfo object with all device details.

Example:

const info = await AlphynSDK.getDeviceInfo();
console.log('Device ID:', info.deviceId);
console.log('App Hash:', info.appHash);
console.log('Initialized:', info.isInitialized);
console.log('Device Initialized:', info.deviceInitialized);
console.log('Last Scan:', info.lastScanDate);

getDeviceId()

Get unique device identifier.

static async getDeviceId(): Promise<string>

Returns: Persistent device ID string.

getAppHash()

Get application binary hash for integrity verification.

static async getAppHash(): Promise<string>

Returns: Application hash string.

getLastScanDate()

Get the date of the last security scan.

static async getLastScanDate(): Promise<Date | null>

Returns: Date of last scan, or null if never scanned.

Security Scanning

Security Scanning Methods

Method	Returns	Description
`performScan()`	`Promise<ScanResult>`	Returns a normalized cross-platform security snapshot.
`getAllRiskFactors()`	`Promise<string[]>`	Returns all detected risk factors.
`getRejectReasons()`	`Promise<string[]>`	Returns normalized rejection reasons.
`getScanResult()`	`Promise<string>`	Returns the raw native scan summary string.
`getAllScanResults(startDate?, endDate?)`	`Promise<string[]>`	Returns historical scan results, optionally filtered by date.
`getModules()`	`Promise<string[]>`	Returns enabled or loaded security modules.

performScan()

Perform a comprehensive security scan to detect threats immediately. This is the recommended primary entry point.

static async performScan(): Promise<ScanResult>

Returns: ScanResult object with normalized scan results.

Example:

const result = await AlphynSDK.performScan();

if (!result.isSafe) {
  console.warn('Device compromised!');
  console.log('Primary threat:', result.primaryRiskFactor);
  console.log('All threats:', result.allRiskFactors);
  console.log('Reasons:', result.rejectReasons);
}

getAllRiskFactors()

Get all detected risk factors from the last scan.

static async getAllRiskFactors(): Promise<string[]>

Returns: Array of risk factor strings.

getRejectReasons()

Get normalized rejection reasons on both platforms.

static async getRejectReasons(): Promise<string[]>

Returns: Array of rejection reason strings.

getScanResult()

Get the raw native scan summary string.

static async getScanResult(): Promise<string>

Returns: Formatted scan summary string from the native SDK.

getAllScanResults()

Get historical scan results with optional date filtering.

static async getAllScanResults(
  startDate?: Date,
  endDate?: Date
): Promise<string[]>

Example:

// Get all results
const allResults = await AlphynSDK.getAllScanResults();

// Get results from last 24 hours
const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000);
const recentResults = await AlphynSDK.getAllScanResults(yesterday, new Date());

getModules()

Get list of enabled or loaded security modules.

static async getModules(): Promise<string[]>

Returns: Array of module names.

Action Verification

High-risk actions are verified with signAction, which signs the transaction with a hardware-backed key belonging to an enrolled user and returns a short-lived token your backend validates server-side. See MFA Transaction Signing for the three-call flow, and MFA on React Native for the signatures.

`signAction` returns the same `ActionVerificationResult` documented below.

Security Event Listeners

Event Methods

Method	Returns	Description
`addSecurityListener(callback)`	`{ remove(): void }`	Cross-platform event listener registration. `callback` uses the `AlphynSecurityListener` type.
`removeAllSecurityListeners()`	`void`	Removes every active JS listener.
`securityEvents(callback)`	`() => void`	Shared Android-only event helper for multiple `AlphynSecurityListener` subscribers.

addSecurityListener()

Add a security event listener to receive real-time security events. Works on both iOS and Android.

static addSecurityListener(
  callback: AlphynSecurityListener
): { remove: () => void }

Parameters:

Name	Type	Description
callback	AlphynSecurityListener	Function called when security events occur

Returns: Subscription object with remove() method.

Example:

import {
  AlphynSDK,
  type AlphynSecurityListener,
} from '@alphyn/react-native-sdk';

const listener: AlphynSecurityListener = (event) => {
  console.log('Operation Type:', event.operationType);
  console.log('Operation Result:', event.operationResult);
  console.log('Original Event Type:', event.originalEventType);
  console.log('Message:', event.message);
  console.log('Details:', event.details);
};

const subscription = AlphynSDK.addSecurityListener(listener);

// Cleanup when component unmounts
subscription.remove();

removeAllSecurityListeners()

Remove all registered security listeners.

static removeAllSecurityListeners(): void

Platform-Specific and Compatibility Methods

Method	Platform	Returns	Description
`setAndroidInterval(intervalSeconds)`	Android	`Promise<void>`	Updates the Android scan interval after initialization.
`enableAndroidListeners(config)`	Android	`Promise<void>`	Convenience wrapper for `initialize()` before using `securityEvents()`.
`initializeAndroid(config?)`	Android	`Promise<void>`	Android alias for `initialize()`.
`isDeviceInitialized()`	Android	`Promise<string>`	Returns the native device init flag string.
`getIOSRejectReasons()`	iOS	`Promise<string[]>`	iOS alias for `getRejectReasons()`.
`getIOSAllScanResults(options?)`	iOS	`Promise<string[]>`	iOS alias for `getAllScanResults()`.
`getResult()`	Both	`Promise<string>`	Deprecated alias for `getScanResult()`.
`clearAll()`	Both	`Promise<void>`	Unsupported. Always throws `NOT_SUPPORTED`.

securityEvents() Android only

Subscribe to the shared security event stream. Unlike addSecurityListener(), this uses a single native listener that broadcasts to all JavaScript subscribers.

static securityEvents(
  callback: AlphynSecurityListener
): () => void

Returns: Unsubscribe function.

Example:

const unsubscribe = AlphynSDK.securityEvents((event) => {
  console.log('Shared Android event:', event.originalEventType);
});

// Later, unsubscribe
unsubscribe();

setAndroidInterval() Android only

Set the scan interval for Android.

static async setAndroidInterval(intervalSeconds: number): Promise<void>

Example:

await AlphynSDK.setAndroidInterval(60); // 60 seconds

isDeviceInitialized() Android only

Get device initialization status on the server.

static async isDeviceInitialized(): Promise<string>

Returns: "true", "false", or "" (if not yet determined).

Types

AlphynConfig

interface AlphynConfig {
  /** Scan interval in seconds. Must be greater than 8. Default: 45 */
  scanInterval?: number;
  /** Development debug hash, applied only when running on Android. */
  androidDebugHash?: string;
  /** Development debug hash, applied only when running on iOS. */
  iosDebugHash?: string;
}

DeviceInfo

interface DeviceInfo {
  deviceId: string;           // Unique device identifier
  appHash: string;            // Application binary hash
  isInitialized: boolean;     // SDK initialization status
  deviceInitialized: string;  // Server registration status
  lastScanDate?: Date;        // Last scan timestamp
}

ScanResult

interface ScanResult {
  isSafe: boolean;            // true if device is secure
  primaryRiskFactor: RiskFactor;  // Main threat (or DEVICE_CLEAN)
  allRiskFactors: RiskFactor[];   // All detected threats
  rejectReasons: string[];    // Human-readable reasons
  scanDate: Date;             // Scan timestamp
  deviceId: string;           // Device ID
  appHash: string;            // App hash
}

ActionVerificationResult

interface ActionVerificationResult {
  success: boolean;           // Whether verification succeeded
  verificationToken?: string; // JWT token (if successful)
  expiresAt?: number;         // Token expiration (epoch ms)
  errorCode?: string;         // Error code (if failed)
  errorMessage?: string;      // Error message (if failed)
}

ActionContext

interface ActionContext {
  [key: string]: string | number | boolean | null | undefined;
}

AlphynCallbackResult

interface AlphynCallbackResult {
  operationType: OperationType;       // What operation triggered this
  operationResult: OperationResult;   // Result of the operation
  originalEventType: AlphynEventType; // Native SDK event type
  message: string;                    // Human-readable message
  details?: string;                   // Additional details
}

AlphynSecurityListener

The React Native listener signature that corresponds to the native AlphynSecurityListener concept on iOS and Android.

type AlphynSecurityListener = (
  event: AlphynCallbackResult
) => void;

Enums

AlphynErrorCode

enum AlphynErrorCode {
  ARG_ERROR = 'ARG_ERROR',           // Invalid argument
  INIT_FAILED = 'INIT_FAILED',       // Initialization failed
  NOT_INITIALIZED = 'NOT_INITIALIZED', // SDK not initialized
  SECURITY_VIOLATION = 'SECURITY_VIOLATION', // Security threat detected
  NETWORK_ERROR = 'NETWORK_ERROR',   // Network request failed
  NOT_SUPPORTED = 'NOT_SUPPORTED',   // Platform not supported
  UNKNOWN = 'UNKNOWN',               // Unknown error
}

RiskFactor

enum RiskFactor {
  DEVICE_CLEAN = 'DEVICE_CLEAN',     // No threats detected
  ROOTED = 'ROOTED',                 // Device is rooted (Android)
  JAILBROKEN = 'JAILBROKEN',         // Device is jailbroken (iOS)
  FRIDA_DETECTED = 'FRIDA_DETECTED', // Frida debugging tool
  EMULATOR = 'EMULATOR',             // Emulator/simulator
  TAMPERED = 'TAMPERED',             // App binary tampered
  DEBUGGER = 'DEBUGGER',             // Debugger attached
  HOOKING = 'HOOKING',               // Hooking framework detected
  MAGISK = 'MAGISK',                 // Magisk detected
  XPOSED = 'XPOSED',                 // Xposed framework
  VPN = 'VPN',                       // VPN connection
  PROXY = 'PROXY',                   // Proxy detected
  DEVELOPER_OPTIONS = 'DEVELOPER_OPTIONS', // Dev options enabled
  USB_DEBUGGING = 'USB_DEBUGGING',   // USB debugging enabled
  SCREEN_MIRRORING = 'SCREEN_MIRRORING', // Screen mirroring active
  ACCESSIBILITY_ABUSE = 'ACCESSIBILITY_ABUSE', // Accessibility abuse
  OVERLAY_ATTACK = 'OVERLAY_ATTACK', // Overlay attack possible
  KEYLOGGER = 'KEYLOGGER',           // Keylogger detected
  SCREEN_CAPTURE = 'SCREEN_CAPTURE', // Screen capture detected
  SSL_PINNING_BYPASS = 'SSL_PINNING_BYPASS', // SSL pinning bypass
  UNKNOWN = 'UNKNOWN',               // Unknown risk
}

OperationType

enum OperationType {
  INITIALIZATION = 'INITIALIZATION',
  SECURITY_SCAN = 'SECURITY_SCAN',
  SCAN_RESPONSE = 'SCAN_RESPONSE',
  NETWORK = 'NETWORK',
  STORAGE = 'STORAGE',
  CALLBACK = 'CALLBACK',
  UNKNOWN = 'UNKNOWN',
}

OperationResult

enum OperationResult {
  SUCCESS = 'SUCCESS',
  FAILURE = 'FAILURE',
  THREAT_DETECTED = 'THREAT_DETECTED',
}

AlphynEventType

enum AlphynEventType {
  INIT_COMPLETE = 'INIT_COMPLETE',
  INIT_FAILED = 'INIT_FAILED',
  FIRST_INIT = 'FIRST_INIT',
  INVALID_APP_KEY = 'INVALID_APP_KEY',
  THREAT_DETECTED = 'THREAT_DETECTED',
  SECURE_DEVICE = 'SECURE_DEVICE',
  INVALID_DATE_OR_TIME = 'INVALID_DATE_OR_TIME',
  KEYSTORE_SUCCESS = 'KEYSTORE_SUCCESS',
  KEYSTORE_FAILED = 'KEYSTORE_FAILED',
  NETWORK_INIT = 'NETWORK_INIT',
  NETWORK_MTLS = 'NETWORK_MTLS',
  JWT_AUTH_SUCCESS = 'JWT_AUTH_SUCCESS',
  SCAN_SUCCESS = 'SCAN_SUCCESS',
  SCAN_RESPONSE = 'SCAN_RESPONSE',
  KEY_EXCHANGE_SUCCESS = 'KEY_EXCHANGE_SUCCESS',
  KEYS_FOUND_STORAGE = 'KEYS_FOUND_STORAGE',
  KEYS_CREATED_NEW = 'KEYS_CREATED_NEW',
  CALLBACK_SUCCESS = 'CALLBACK_SUCCESS',
  CALLBACK_FAILED = 'CALLBACK_FAILED',
  NETWORK_ERROR = 'NETWORK_ERROR',
  AUTH_FAILED = 'AUTH_FAILED',
  SCAN_FAILED = 'SCAN_FAILED',
  REQUEST_FAILED = 'REQUEST_FAILED',
  RISK_FACTOR_DETECTED = 'RISK_FACTOR_DETECTED',
  UNKNOWN = 'UNKNOWN',
}

AlphynScanResult

enum AlphynScanResult {
  TRUSTED = 'TRUSTED',
  FLAGGED = 'FLAGGED',
  UNTRUSTED = 'UNTRUSTED',
  UNKNOWN = 'UNKNOWN',
  INITIALIZATION_ERROR = 'INITIALIZATION_ERROR',
}

Note: AlphynScanResult (and AlphynScanResultHelpers) are optional helpers for building your own status model - no SDK method returns this enum. performScan() returns a ScanResult object based on RiskFactor values.

Error Handling

All SDK methods may throw AlphynError. Always wrap SDK calls in try-catch blocks.

import { AlphynError, AlphynErrorCode, AlphynSDK } from '@alphyn/react-native-sdk';

try {
  await AlphynSDK.initialize({ scanInterval: 5 });
} catch (error) {
  if (AlphynError.isAlphynError(error)) {
    switch (error.code) {
      case AlphynErrorCode.ARG_ERROR:
        console.error('Argument error:', error.message);
        break;
      case AlphynErrorCode.INIT_FAILED:
        console.error('Initialization failed:', error.message);
        break;
      case AlphynErrorCode.NOT_INITIALIZED:
        console.error('SDK not initialized');
        break;
      default:
        console.error('Unexpected Alphyn error:', error.message);
    }
  }
}

Common Error Codes

Code	Meaning
`ARG_ERROR`	Invalid argument such as an interval below the supported minimum
`INIT_FAILED`	SDK initialization failed
`NOT_INITIALIZED`	A method was called before initialization
`SECURITY_VIOLATION`	A threat or security violation was detected
`NETWORK_ERROR`	A network or backend request failed
`NOT_SUPPORTED`	The method is not available on the current platform
`UNKNOWN`	Any unmapped or unexpected error

AlphynError

class AlphynError extends Error {
  code: AlphynErrorCode;
  message: string;

  static isAlphynError(error: unknown): error is AlphynError;
  static fromNative(error: any): AlphynError;
  static notSupported(method: string, platform: string): AlphynError;
  static invalidArgument(name: string, reason: string): AlphynError;
}

API Reference

AlphynSDK

Core Methods

Initialization

initialize()

isInitialized()

Device Information

getDeviceInfo()

getDeviceId()

getAppHash()

getLastScanDate()

Security Scanning

Security Scanning Methods

performScan()

getAllRiskFactors()

getRejectReasons()

getScanResult()

getAllScanResults()

getModules()

Action Verification

signAction returns the same ActionVerificationResult documented below.

Security Event Listeners

Event Methods

addSecurityListener()

removeAllSecurityListeners()

Platform-Specific and Compatibility Methods

securityEvents() Android only

setAndroidInterval() Android only

isDeviceInitialized() Android only

Types

AlphynConfig

DeviceInfo

ScanResult

ActionVerificationResult

ActionContext

AlphynCallbackResult

AlphynSecurityListener

Enums

AlphynErrorCode

RiskFactor

OperationType

OperationResult

AlphynEventType

AlphynScanResult

Error Handling

Common Error Codes

AlphynError

`signAction` returns the same `ActionVerificationResult` documented below.