react-native-device-integrity 0.1.0 → 0.2.0

package/src/resolveStatus.ts

@@ -4,6 +4,7 @@ import type {
   IntegrityResult,
   Signal,
   SignalCategory,
+  SignalId,
   UnknownReason,
 } from './types';
 
@@ -17,6 +18,16 @@ const SIGNAL_CATEGORIES: ReadonlySet<string> = new Set([
   'environment',
 ]);
 
+/** Default compromising set: every category except emulator. */
+const DEFAULT_COMPROMISING_CATEGORIES: readonly SignalCategory[] = [
+  'jailbreak',
+  'root',
+  'hooking',
+  'debugger',
+  'tamper',
+  'environment',
+];
+
 function coerceCategory(category: unknown): SignalCategory {
   if (typeof category === 'string' && SIGNAL_CATEGORIES.has(category)) {
     return category as SignalCategory;
@@ -48,6 +59,46 @@ function normalizeSignal(raw: unknown): Signal {
   };
 }
 
+function resolveCompromisingCategories(
+  options: CheckIntegrityOptions
+): ReadonlySet<SignalCategory> {
+  const base =
+    options.policy?.compromisingCategories != null
+      ? options.policy.compromisingCategories
+      : DEFAULT_COMPROMISING_CATEGORIES;
+
+  const set = new Set<SignalCategory>(base);
+
+  if (options.treatEmulatorAsCompromised === true) {
+    set.add('emulator');
+  }
+
+  return set;
+}
+
+function partitionIgnored(
+  signals: Signal[],
+  ignore: SignalId[] | undefined
+): { active: Signal[]; ignored: Signal[] } {
+  if (ignore == null || ignore.length === 0) {
+    return { active: signals, ignored: [] };
+  }
+
+  const ignoreSet = new Set<string>(ignore);
+  const active: Signal[] = [];
+  const ignored: Signal[] = [];
+
+  for (const signal of signals) {
+    if (ignoreSet.has(signal.id)) {
+      ignored.push(signal);
+    } else {
+      active.push(signal);
+    }
+  }
+
+  return { active, ignored };
+}
+
 function malformed(
   platform: typeof Platform.OS,
   error: string
@@ -55,6 +106,8 @@ function malformed(
   return {
     status: 'unknown',
     signals: [],
+    ignored: [],
+    durationMs: 0,
     platform,
     reason: 'native_error',
     error,
@@ -64,6 +117,7 @@ function malformed(
 /**
  * Maps a native integrity report + options to the public IntegrityResult.
  * Compromise evidence wins over incomplete runs; incomplete/malformed never become 'clean'.
+ * `durationMs` is set to 0 here — `checkIntegrity` overwrites with measured wall time.
  */
 export function resolveStatus(
   report: unknown,
@@ -80,25 +134,24 @@ export function resolveStatus(
     return malformed(platform, 'Malformed native integrity report');
   }
 
-  const signals = nativeReport.signals.map(normalizeSignal);
+  const allSignals = nativeReport.signals.map(normalizeSignal);
+  const { active: signals, ignored } = partitionIgnored(
+    allSignals,
+    options.ignore
+  );
   const completed = nativeReport.completed === true;
-  const treatEmulatorAsCompromised =
-    options.treatEmulatorAsCompromised === true;
+  const compromising = resolveCompromisingCategories(options);
 
-  const hasNonEmulatorSignal = signals.some(
-    (signal) => signal.category !== 'emulator'
-  );
-  const hasEmulatorSignal = signals.some(
-    (signal) => signal.category === 'emulator'
+  const hasCompromisingSignal = signals.some((signal) =>
+    compromising.has(signal.category)
   );
 
-  if (
-    hasNonEmulatorSignal ||
-    (hasEmulatorSignal && treatEmulatorAsCompromised)
-  ) {
+  if (hasCompromisingSignal) {
     return {
       status: 'compromised',
       signals,
+      ignored,
+      durationMs: 0,
       platform,
     };
   }
@@ -112,6 +165,8 @@ export function resolveStatus(
     return {
       status: 'unknown',
       signals,
+      ignored,
+      durationMs: 0,
       platform,
       reason,
     };
@@ -120,6 +175,8 @@ export function resolveStatus(
   return {
     status: 'clean',
     signals,
+    ignored,
+    durationMs: 0,
     platform,
   };
 }

package/src/types.ts

@@ -11,8 +11,38 @@ export type SignalCategory =
   | 'tamper'
   | 'environment';
 
+/**
+ * Stable public signal ids. Unknown future ids remain accepted on `Signal.id`.
+ */
+export const SIGNAL_IDS = [
+  'simulator',
+  'jailbreak_files',
+  'jailbreak_url_schemes',
+  'jailbreak_symlinks',
+  'jailbreak_writable_system',
+  'hooking_libraries',
+  'hooking_dyld_insert',
+  'debugger_attached',
+  'emulator',
+  'root_su_binary',
+  'root_management_apps',
+  'root_magisk_files',
+  'root_test_keys',
+  'root_dangerous_props',
+  'root_rw_system',
+  'hooking_frida',
+  'hooking_xposed',
+  'tamper_signature_mismatch',
+  'tamper_untrusted_installer',
+  'tamper_binary_decrypted',
+  'tamper_team_id_mismatch',
+] as const;
+
+export type SignalId = (typeof SIGNAL_IDS)[number];
+
 export interface Signal {
-  id: string;
+  /** Known ids autocomplete; unknown future ids are still accepted. */
+  id: SignalId | (string & {});
   category: SignalCategory;
   description: string;
 }
@@ -28,14 +58,58 @@ export type UnknownReason =
 export interface IntegrityResult {
   status: IntegrityStatus;
   signals: Signal[];
+  /** Signals removed by `ignore` — never affect status. Always present. */
+  ignored: Signal[];
+  /** Wall time of the check in JS (monotonic when available). 0 on unsupported platforms. */
+  durationMs: number;
   platform: typeof Platform.OS;
   reason?: UnknownReason;
   error?: string;
 }
 
+export interface AndroidIntegrityOptions {
+  /** SHA-256 digests of expected signing certificates (hex; colons/whitespace optional). */
+  expectedSigningCertificates?: string[];
+  /** Package names of allowed installers (e.g. `com.android.vending`). */
+  allowedInstallers?: string[];
+}
+
+export interface IosIntegrityOptions {
+  /** Expected Apple Team IDs (keychain access-group prefix). */
+  expectedTeamIds?: string[];
+  /** When true, require the main executable to be encrypted (App Store / TestFlight). */
+  requireEncryptedBinary?: boolean;
+}
+
+export interface IntegrityPolicy {
+  /**
+   * Categories that make status `'compromised'`.
+   * When omitted, defaults to every category except `'emulator'`.
+   */
+  compromisingCategories?: SignalCategory[];
+}
+
 export interface CheckIntegrityOptions {
-  /** Treat emulator/simulator signals as compromising. Default false (reported, but status stays 'clean'). */
+  /**
+   * Treat emulator/simulator signals as compromising. Default false (reported,
+   * but status stays 'clean' unless the category is otherwise in the policy set).
+   * Shorthand that unions `'emulator'` into the compromising category set.
+   */
   treatEmulatorAsCompromised?: boolean;
   /** Resolve as 'unknown' with reason 'timeout' if native does not answer in time. Default 10000 ms. */
   timeoutMs?: number;
+  /**
+   * Signal ids to exclude from status resolution. Matching signals move to
+   * `result.ignored` and never affect status.
+   */
+  ignore?: SignalId[];
+  /**
+   * Status policy. `compromisingCategories` replaces the default set when
+   * provided; `treatEmulatorAsCompromised` is unioned in when both are set.
+   */
+  policy?: IntegrityPolicy;
+  /** Android-only tamper options forwarded to native when provided. */
+  android?: AndroidIntegrityOptions;
+  /** iOS-only tamper options forwarded to native when provided. */
+  ios?: IosIntegrityOptions;
 }

package/src/useDeviceIntegrity.ts

@@ -16,11 +16,27 @@ export type UseDeviceIntegrityResult = {
   refresh: () => Promise<IntegrityResult>;
 };
 
+/**
+ * Stable serialization of options that affect the check. Inline object literals
+ * with the same values must not retrigger the effect.
+ */
+function optionsKey(options: CheckIntegrityOptions): string {
+  return JSON.stringify({
+    treatEmulatorAsCompromised: options.treatEmulatorAsCompromised === true,
+    timeoutMs: options.timeoutMs,
+    ignore: options.ignore,
+    policy: options.policy,
+    android: options.android,
+    ios: options.ios,
+  });
+}
+
 export function useDeviceIntegrity(
   options: CheckIntegrityOptions = {}
 ): UseDeviceIntegrityResult {
-  const treatEmulatorAsCompromised = options.treatEmulatorAsCompromised;
-  const timeoutMs = options.timeoutMs;
+  const key = optionsKey(options);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
 
   const [result, setResult] = useState<IntegrityResult | null>(null);
   const [loading, setLoading] = useState(true);
@@ -33,10 +49,7 @@ export function useDeviceIntegrity(
     const requestId = ++requestIdRef.current;
     setLoading(true);
 
-    const next = await checkIntegrity({
-      treatEmulatorAsCompromised,
-      timeoutMs,
-    });
+    const next = await checkIntegrity(optionsRef.current);
 
     if (mountedRef.current && requestId === requestIdRef.current) {
       setResult(next);
@@ -44,7 +57,9 @@ export function useDeviceIntegrity(
     }
 
     return next;
-  }, [treatEmulatorAsCompromised, timeoutMs]);
+    // `key` is the by-value options fingerprint (not used in the body; optionsRef is).
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- equal-by-value options
+  }, [key]);
 
   useEffect(() => {
     mountedRef.current = true;