react-native-device-integrity 0.1.0

package/src/resolveStatus.ts

@@ -0,0 +1,125 @@
+import type { Platform } from 'react-native';
+import type {
+  CheckIntegrityOptions,
+  IntegrityResult,
+  Signal,
+  SignalCategory,
+  UnknownReason,
+} from './types';
+
+const SIGNAL_CATEGORIES: ReadonlySet<string> = new Set([
+  'jailbreak',
+  'root',
+  'hooking',
+  'debugger',
+  'emulator',
+  'tamper',
+  'environment',
+]);
+
+function coerceCategory(category: unknown): SignalCategory {
+  if (typeof category === 'string' && SIGNAL_CATEGORIES.has(category)) {
+    return category as SignalCategory;
+  }
+  return 'environment';
+}
+
+function normalizeSignal(raw: unknown): Signal {
+  if (raw === null || typeof raw !== 'object') {
+    return {
+      id: 'unknown_signal',
+      category: 'environment',
+      description: '',
+    };
+  }
+
+  const signal = raw as Record<string, unknown>;
+  const id =
+    typeof signal.id === 'string' && signal.id.length > 0
+      ? signal.id
+      : 'unknown_signal';
+  const description =
+    typeof signal.description === 'string' ? signal.description : '';
+
+  return {
+    id,
+    category: coerceCategory(signal.category),
+    description,
+  };
+}
+
+function malformed(
+  platform: typeof Platform.OS,
+  error: string
+): IntegrityResult {
+  return {
+    status: 'unknown',
+    signals: [],
+    platform,
+    reason: 'native_error',
+    error,
+  };
+}
+
+/**
+ * Maps a native integrity report + options to the public IntegrityResult.
+ * Compromise evidence wins over incomplete runs; incomplete/malformed never become 'clean'.
+ */
+export function resolveStatus(
+  report: unknown,
+  options: CheckIntegrityOptions = {},
+  platform: typeof Platform.OS
+): IntegrityResult {
+  if (report === null || typeof report !== 'object' || Array.isArray(report)) {
+    return malformed(platform, 'Malformed native integrity report');
+  }
+
+  const nativeReport = report as Record<string, unknown>;
+
+  if (!Array.isArray(nativeReport.signals)) {
+    return malformed(platform, 'Malformed native integrity report');
+  }
+
+  const signals = nativeReport.signals.map(normalizeSignal);
+  const completed = nativeReport.completed === true;
+  const treatEmulatorAsCompromised =
+    options.treatEmulatorAsCompromised === true;
+
+  const hasNonEmulatorSignal = signals.some(
+    (signal) => signal.category !== 'emulator'
+  );
+  const hasEmulatorSignal = signals.some(
+    (signal) => signal.category === 'emulator'
+  );
+
+  if (
+    hasNonEmulatorSignal ||
+    (hasEmulatorSignal && treatEmulatorAsCompromised)
+  ) {
+    return {
+      status: 'compromised',
+      signals,
+      platform,
+    };
+  }
+
+  if (!completed) {
+    const reason: UnknownReason =
+      nativeReport.reason === 'not_implemented'
+        ? 'not_implemented'
+        : 'incomplete';
+
+    return {
+      status: 'unknown',
+      signals,
+      platform,
+      reason,
+    };
+  }
+
+  return {
+    status: 'clean',
+    signals,
+    platform,
+  };
+}

package/src/types.ts

@@ -0,0 +1,41 @@
+import type { Platform } from 'react-native';
+
+export type IntegrityStatus = 'clean' | 'compromised' | 'unknown';
+
+export type SignalCategory =
+  | 'jailbreak'
+  | 'root'
+  | 'hooking'
+  | 'debugger'
+  | 'emulator'
+  | 'tamper'
+  | 'environment';
+
+export interface Signal {
+  id: string;
+  category: SignalCategory;
+  description: string;
+}
+
+export type UnknownReason =
+  | 'unsupported_platform'
+  | 'native_module_unavailable'
+  | 'native_error'
+  | 'timeout'
+  | 'incomplete'
+  | 'not_implemented';
+
+export interface IntegrityResult {
+  status: IntegrityStatus;
+  signals: Signal[];
+  platform: typeof Platform.OS;
+  reason?: UnknownReason;
+  error?: string;
+}
+
+export interface CheckIntegrityOptions {
+  /** Treat emulator/simulator signals as compromising. Default false (reported, but status stays 'clean'). */
+  treatEmulatorAsCompromised?: boolean;
+  /** Resolve as 'unknown' with reason 'timeout' if native does not answer in time. Default 10000 ms. */
+  timeoutMs?: number;
+}

package/src/useDeviceIntegrity.ts

@@ -0,0 +1,92 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { AppState, type AppStateStatus } from 'react-native';
+import { checkIntegrity } from './checkIntegrity';
+import type {
+  CheckIntegrityOptions,
+  IntegrityResult,
+  IntegrityStatus,
+  Signal,
+} from './types';
+
+export type UseDeviceIntegrityResult = {
+  status: IntegrityStatus;
+  signals: Signal[];
+  result: IntegrityResult | null;
+  loading: boolean;
+  refresh: () => Promise<IntegrityResult>;
+};
+
+export function useDeviceIntegrity(
+  options: CheckIntegrityOptions = {}
+): UseDeviceIntegrityResult {
+  const treatEmulatorAsCompromised = options.treatEmulatorAsCompromised;
+  const timeoutMs = options.timeoutMs;
+
+  const [result, setResult] = useState<IntegrityResult | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  const requestIdRef = useRef(0);
+  const mountedRef = useRef(true);
+  const appStateRef = useRef(AppState.currentState);
+
+  const run = useCallback(async (): Promise<IntegrityResult> => {
+    const requestId = ++requestIdRef.current;
+    setLoading(true);
+
+    const next = await checkIntegrity({
+      treatEmulatorAsCompromised,
+      timeoutMs,
+    });
+
+    if (mountedRef.current && requestId === requestIdRef.current) {
+      setResult(next);
+      setLoading(false);
+    }
+
+    return next;
+  }, [treatEmulatorAsCompromised, timeoutMs]);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    run().catch(() => {
+      // checkIntegrity never rejects; guard against unexpected throws
+    });
+
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [run]);
+
+  useEffect(() => {
+    const onChange = (nextState: AppStateStatus) => {
+      const previous = appStateRef.current;
+      appStateRef.current = nextState;
+
+      if (
+        (previous === 'background' || previous === 'inactive') &&
+        nextState === 'active'
+      ) {
+        run().catch(() => {
+          // checkIntegrity never rejects; guard against unexpected throws
+        });
+      }
+    };
+
+    const subscription = AppState.addEventListener('change', onChange);
+    return () => {
+      subscription.remove();
+    };
+  }, [run]);
+
+  const refresh = useCallback((): Promise<IntegrityResult> => {
+    return run();
+  }, [run]);
+
+  return {
+    status: result?.status ?? 'unknown',
+    signals: result?.signals ?? [],
+    result,
+    loading,
+    refresh,
+  };
+}