react-native-rootbeer-checkroot 0.1.0

package/README.md

@@ -0,0 +1,799 @@
+# react-native-root-beer
+
+A **React Native New Architecture (TurboModule)** wrapper around the battle-tested Android root detection library [`com.scottyab:rootbeer-lib`](https://github.com/scottyab/rootbeer). It exposes 12 granular detection methods over JSI (JavaScript Interface) — no bridge overhead, no threading surprises.
+
+> **⚠️ Android Only.** This library is strictly an Android module. Its TurboModule is registered with `TurboModuleRegistry.getEnforcing`, which means calling any method on a non-Android platform (iOS, web) will throw a runtime error. All calls must be guarded with `Platform.OS === 'android'`.
+
+---
+
+## Table of Contents
+
+- [How It Works](#how-it-works)
+- [Requirements](#requirements)
+- [Installation](#installation)
+  - [Bare React Native](#bare-react-native)
+  - [Expo (Managed & Bare Workflow)](#expo-managed--bare-workflow)
+- [Native Android Configuration](#native-android-configuration)
+- [Usage Guide](#usage-guide)
+  - [Quick Start — Single Root Check](#quick-start--single-root-check)
+  - [Granular Detection Scan](#granular-detection-scan)
+  - [Reusable React Hook](#reusable-react-hook)
+  - [Navigation Guard Pattern](#navigation-guard-pattern)
+- [API Reference](#api-reference)
+- [Detection Method Deep Dive](#detection-method-deep-dive)
+- [Platform Guard Reference](#platform-guard-reference)
+- [Architecture](#architecture)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## How It Works
+
+`react-native-root-beer` is built as a **TurboModule** using React Native's New Architecture (Codegen). Instead of going through the old asynchronous JS bridge, every method call crosses the native boundary via JSI — synchronously and with zero serialization overhead.
+
+The library ships its own `android/build.gradle` which declares `com.scottyab:rootbeer-lib:0.1.2` as a Gradle `implementation` dependency. When any consumer app installs this package, Gradle resolves and downloads the RootBeer SDK automatically as a **transitive dependency**. You never need to touch your app's `android/` folder.
+
+---
+
+## Requirements
+
+| Requirement | Version |
+|---|---|
+| React Native | ≥ 0.73 (New Architecture required) |
+| Android `minSdkVersion` | **24** (Android 7.0 Nougat) |
+| Android `compileSdkVersion` | 36 |
+| Java source/target compatibility | **17** |
+| Kotlin | 2.0.21 (bundled in the library) |
+| `react-native-root-beer` | 0.1.0 |
+
+> **New Architecture is mandatory.** This library is a TurboModule — it does not have an Old Architecture (bridge) fallback. Ensure `newArchEnabled=true` is set in your project's `android/gradle.properties`.
+
+---
+
+## Installation
+
+### Bare React Native
+
+**Step 1 — Install the package**
+
+```bash
+# npm
+npm install react-native-root-beer
+
+# yarn
+yarn add react-native-root-beer
+```
+
+**Step 2 — Enable New Architecture**
+
+Open `android/gradle.properties` and confirm the following line is present and not commented out:
+
+```properties
+# android/gradle.properties
+newArchEnabled=true
+```
+
+**Step 3 — Rebuild the native layer**
+
+```bash
+cd android && ./gradlew clean
+cd ..
+npx react-native run-android
+```
+
+Gradle will automatically resolve `com.scottyab:rootbeer-lib:0.1.2` from Maven Central during this build. No manual `build.gradle` edits are required.
+
+---
+
+### Expo (Managed & Bare Workflow)
+
+Because this library contains native Android code, it **cannot** run in the Expo Go client. You must use a [development build](https://docs.expo.dev/develop/development-builds/introduction/).
+
+**Step 1 — Install the package**
+
+```bash
+npx expo install react-native-root-beer
+```
+
+**Step 2 — Enable New Architecture in your Expo config**
+
+In `app.json` or `app.config.js`, ensure the new architecture flag is set:
+
+```json
+{
+  "expo": {
+    "android": {
+      "newArchEnabled": true
+    }
+  }
+}
+```
+
+**Step 3 — Run prebuild**
+
+```bash
+npx expo prebuild --platform android
+```
+
+> **Why this is safe with Expo:** The library declares its own Gradle dependency inside its own `android/build.gradle`. When `expo prebuild` (re)generates the native `android/` folder, it does **not** wipe library-level Gradle files — only the app-level files are regenerated. Your native configuration is therefore **upgrade-safe** and survives every future `expo prebuild` run.
+
+**Step 4 — Build a development client or production build**
+
+```bash
+# Development build (EAS)
+eas build --profile development --platform android
+
+# Or run locally
+npx expo run:android
+```
+
+---
+
+## Native Android Configuration
+
+**None required.**
+
+This is the primary design goal of `react-native-root-beer`. The `com.scottyab:rootbeer-lib:0.1.2` dependency is declared inside the library's own `android/build.gradle`:
+
+```groovy
+// This lives inside the library — you do not write this yourself.
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "com.scottyab:rootbeer-lib:0.1.2"
+}
+```
+
+Gradle's dependency resolution propagates this to your app's build graph automatically.
+
+**No `AndroidManifest.xml` permissions are needed.** The library's own manifest is empty — root detection is performed entirely through file-system introspection, system property reads, and process execution, none of which require declared permissions on Android.
+
+---
+
+## Usage Guide
+
+### Quick Start — Single Root Check
+
+The simplest possible integration. Use `RootBeer.isRooted()` to run all available checks in one call.
+
+```typescript
+import React, { useEffect, useState } from 'react';
+import { Platform, Text, View, StyleSheet } from 'react-native';
+import { RootBeer } from 'react-native-root-beer';
+
+export default function App() {
+  const [isRooted, setIsRooted] = useState<boolean | null>(null);
+
+  useEffect(() => {
+    // Always guard with Platform.OS — this library is Android-only.
+    if (Platform.OS === 'android') {
+      const result = RootBeer.isRooted();
+      setIsRooted(result);
+    }
+  }, []);
+
+  if (Platform.OS !== 'android') {
+    return (
+      <View style={styles.container}>
+        <Text>Root detection is only available on Android.</Text>
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.container}>
+      {isRooted === null ? (
+        <Text>Checking device integrity...</Text>
+      ) : (
+        <Text style={isRooted ? styles.danger : styles.safe}>
+          {isRooted ? '⚠️ Device is rooted' : '✅ Device is not rooted'}
+        </Text>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1, justifyContent: 'center', alignItems: 'center' },
+  danger: { color: '#e53e3e', fontSize: 18, fontWeight: 'bold' },
+  safe: { color: '#38a169', fontSize: 18, fontWeight: 'bold' },
+});
+```
+
+> **Note:** All `RootBeer` methods are **synchronous**. They return `boolean` directly — no `await`, no `.then()`.
+
+---
+
+### Granular Detection Scan
+
+For security-sensitive applications, run each check individually to understand *why* a device is flagged and log the results for your backend.
+
+```typescript
+import { Platform } from 'react-native';
+import { RootBeer } from 'react-native-root-beer';
+
+interface RootScanResult {
+  isRooted: boolean;
+  isRootedWithoutBusyBoxCheck: boolean;
+  hasRootManagementApps: boolean;
+  hasDangerousApps: boolean;
+  hasTestKeys: boolean;
+  hasSuBinary: boolean;
+  hasMagiskBinary: boolean;
+  suExecutes: boolean;
+  hasDangerousProps: boolean;
+  hasRWPaths: boolean;
+  hasRootCloakingApps: boolean;
+  hasBusyBox: boolean;
+}
+
+/**
+ * Runs every available RootBeer check and returns a structured result.
+ * Call this on Android only.
+ */
+export function performFullRootScan(): RootScanResult {
+  if (Platform.OS !== 'android') {
+    throw new Error('performFullRootScan() is only supported on Android.');
+  }
+
+  return {
+    // High-level composite checks
+    isRooted: RootBeer.isRooted(),
+    isRootedWithoutBusyBoxCheck: RootBeer.isRootedWithoutBusyBoxCheck(),
+
+    // Installed app checks
+    hasRootManagementApps: RootBeer.detectRootManagementApps(),
+    hasDangerousApps: RootBeer.detectPotentiallyDangerousApps(),
+    hasRootCloakingApps: RootBeer.detectRootCloakingApps(),
+
+    // Build / ROM checks
+    hasTestKeys: RootBeer.detectTestKeys(),
+
+    // Binary presence checks (static — does not execute anything)
+    hasSuBinary: RootBeer.checkForSuBinary(),
+    hasMagiskBinary: RootBeer.checkForMagiskBinary(),
+    hasBusyBox: RootBeer.checkForBinary('busybox'),
+
+    // Runtime probe (actually attempts to run `su`)
+    suExecutes: RootBeer.checkSuExists(),
+
+    // System property & filesystem checks
+    hasDangerousProps: RootBeer.checkForDangerousProps(),
+    hasRWPaths: RootBeer.checkForRWPaths(),
+  };
+}
+
+// --- Usage ---
+if (Platform.OS === 'android') {
+  const scan = performFullRootScan();
+
+  if (scan.isRooted) {
+    console.warn('Root indicators detected:', scan);
+    // Send `scan` to your analytics / security backend for forensics
+  }
+}
+```
+
+---
+
+### Reusable React Hook
+
+Encapsulate all detection logic in a custom hook for clean, idiomatic React consumption across your app.
+
+```typescript
+// hooks/useRootDetection.ts
+import { useEffect, useState } from 'react';
+import { Platform } from 'react-native';
+import { RootBeer } from 'react-native-root-beer';
+
+interface RootDetectionState {
+  /** True if any root indicator was found. */
+  isRooted: boolean;
+  /** True while the detection is running (first render only). */
+  isChecking: boolean;
+  /** True if the check completed without errors. */
+  isReady: boolean;
+  /** Populated if an unexpected error occurred during detection. */
+  error: Error | null;
+}
+
+/**
+ * Runs `RootBeer.isRooted()` once on mount.
+ * On non-Android platforms, `isRooted` is always `false` and `isReady`
+ * is `false` to prevent false security guarantees.
+ */
+export function useRootDetection(): RootDetectionState {
+  const [state, setState] = useState<RootDetectionState>({
+    isRooted: false,
+    isChecking: Platform.OS === 'android',
+    isReady: false,
+    error: null,
+  });
+
+  useEffect(() => {
+    if (Platform.OS !== 'android') {
+      return;
+    }
+
+    try {
+      const isRooted = RootBeer.isRooted();
+      setState({ isRooted, isChecking: false, isReady: true, error: null });
+    } catch (err) {
+      setState({
+        isRooted: false,
+        isChecking: false,
+        isReady: false,
+        error: err instanceof Error ? err : new Error(String(err)),
+      });
+    }
+  }, []);
+
+  return state;
+}
+```
+
+```typescript
+// components/SecureScreen.tsx
+import React from 'react';
+import { ActivityIndicator, Text, View } from 'react-native';
+import { useRootDetection } from '../hooks/useRootDetection';
+
+export function SecureScreen() {
+  const { isRooted, isChecking, error } = useRootDetection();
+
+  if (isChecking) {
+    return <ActivityIndicator size="large" />;
+  }
+
+  if (error) {
+    // Treat detection failure conservatively — block access
+    return <Text>Security check failed. Access denied.</Text>;
+  }
+
+  if (isRooted) {
+    return (
+      <View>
+        <Text>⚠️ This app cannot run on a rooted device.</Text>
+      </View>
+    );
+  }
+
+  return <Text>✅ Device integrity verified. Welcome!</Text>;
+}
+```
+
+---
+
+### Navigation Guard Pattern
+
+Block access to sensitive screens at the navigation level. This example uses React Navigation, but the pattern applies to any router.
+
+```typescript
+// navigation/RootGuard.tsx
+import React, { useEffect } from 'react';
+import { Platform, Alert } from 'react-native';
+import { useNavigation } from '@react-navigation/native';
+import { RootBeer } from 'react-native-root-beer';
+
+interface RootGuardProps {
+  children: React.ReactNode;
+  /** Screen name to redirect to when root is detected. */
+  fallbackScreen?: string;
+}
+
+/**
+ * Wraps a screen and redirects away if the device is rooted.
+ * Must be rendered inside a React Navigation navigator.
+ */
+export function RootGuard({ children, fallbackScreen = 'Home' }: RootGuardProps) {
+  const navigation = useNavigation();
+
+  useEffect(() => {
+    if (Platform.OS !== 'android') {
+      return;
+    }
+
+    const isRooted = RootBeer.isRooted();
+
+    if (isRooted) {
+      Alert.alert(
+        'Security Warning',
+        'This feature is not available on rooted devices.',
+        [{ text: 'OK', onPress: () => navigation.navigate(fallbackScreen as never) }],
+        { cancelable: false }
+      );
+    }
+  }, [navigation, fallbackScreen]);
+
+  return <>{children}</>;
+}
+```
+
+```typescript
+// Inside your screen component
+function PaymentScreen() {
+  return (
+    <RootGuard fallbackScreen="Home">
+      {/* Sensitive payment UI renders here */}
+    </RootGuard>
+  );
+}
+```
+
+---
+
+## API Reference
+
+All methods are synchronous and return `boolean`. They are exposed on the `RootBeer` object (`as const`) imported from `react-native-root-beer`.
+
+```typescript
+import { RootBeer } from 'react-native-root-beer';
+```
+
+### Method Summary
+
+| Method | Parameters | Returns | Description |
+|---|---|---|---|
+| `isRooted()` | — | `boolean` | Runs **all** detection checks, including BusyBox. The primary, recommended check. |
+| `isRootedWithoutBusyBoxCheck()` | — | `boolean` | Runs all checks **except** BusyBox. Use when BusyBox causes false positives. |
+| `detectRootManagementApps()` | — | `boolean` | Scans installed apps for known root managers (SuperSU, Magisk Manager, KingRoot, etc.). |
+| `detectPotentiallyDangerousApps()` | — | `boolean` | Scans installed apps for apps commonly associated with root exploitation. |
+| `detectRootCloakingApps()` | — | `boolean` | Scans installed apps for apps that conceal root from other apps (RootCloak, Hide My Root). |
+| `detectTestKeys()` | — | `boolean` | Checks `android.os.Build.TAGS` for `"test-keys"` — a signature of unofficial/custom ROMs. |
+| `checkForSuBinary()` | — | `boolean` | Scans a list of known filesystem paths for the `su` executable. **Static — does not execute anything.** |
+| `checkForMagiskBinary()` | — | `boolean` | Scans filesystem paths for the Magisk binary. Effective even when Magisk is in hide mode. |
+| `checkForBinary(binaryName)` | `binaryName: string` | `boolean` | Scans filesystem paths for **any named binary**. Pass `"busybox"`, `"su"`, or any other name. |
+| `checkSuExists()` | — | `boolean` | **Attempts to execute `su`**. Returns `true` if the call succeeds. Runtime probe — more invasive than `checkForSuBinary()`. |
+| `checkForDangerousProps()` | — | `boolean` | Reads system properties and returns `true` if dangerous values are set (e.g. `ro.debuggable=1`, `ro.secure=0`). |
+| `checkForRWPaths()` | — | `boolean` | Inspects `/proc/mounts` for filesystem paths that should be read-only but are mounted read-write. |
+
+---
+
+### Method Detail
+
+#### `RootBeer.isRooted(): boolean`
+
+The top-level composite check. Internally calls every other detection method (including BusyBox) and returns `true` if **any single indicator** is found.
+
+**Use this** for the vast majority of use cases. Only fall back to individual methods when you need to understand which specific indicator triggered.
+
+```typescript
+const safe = !RootBeer.isRooted();
+```
+
+---
+
+#### `RootBeer.isRootedWithoutBusyBoxCheck(): boolean`
+
+Identical to `isRooted()`, but skips the BusyBox binary check. BusyBox is a legitimate developer tool that may be present on non-malicious devices (e.g. some manufacturer ROMs include it). Use this variant if you are seeing false positives from `isRooted()` in your production user base.
+
+```typescript
+// Prefer this if you're seeing false positives from isRooted()
+const safe = !RootBeer.isRootedWithoutBusyBoxCheck();
+```
+
+---
+
+#### `RootBeer.detectRootManagementApps(): boolean`
+
+Queries the Android `PackageManager` for the package names of well-known root management applications. Returns `true` if any are installed.
+
+**Examples of detected apps:** SuperSU, Magisk Manager, KingRoot, Towelroot, BaiduEasyRoot.
+
+```typescript
+if (RootBeer.detectRootManagementApps()) {
+  console.warn('Root management app found on device.');
+}
+```
+
+---
+
+#### `RootBeer.detectPotentiallyDangerousApps(): boolean`
+
+Queries the `PackageManager` for apps that are commonly used to exploit, abuse, or probe rooted environments — even if they are not root managers themselves.
+
+```typescript
+if (RootBeer.detectPotentiallyDangerousApps()) {
+  console.warn('Potentially dangerous app detected.');
+}
+```
+
+---
+
+#### `RootBeer.detectRootCloakingApps(): boolean`
+
+Scans for root-hiding apps (e.g. RootCloak, MagiskHide-related helpers) whose presence implies a deliberate attempt to conceal root access from the system. A positive result here is a particularly strong signal of malicious intent.
+
+```typescript
+if (RootBeer.detectRootCloakingApps()) {
+  // High-confidence indicator — user is actively trying to hide root
+  console.warn('Root cloaking app detected.');
+}
+```
+
+---
+
+#### `RootBeer.detectTestKeys(): boolean`
+
+Reads `android.os.Build.TAGS` and returns `true` if it contains `"test-keys"`. Production devices from manufacturers are always signed with `"release-keys"`. Test-key builds indicate either a custom ROM or developer engineering builds — both of which typically have root access.
+
+```typescript
+if (RootBeer.detectTestKeys()) {
+  console.warn('Device is running a custom or test-key ROM.');
+}
+```
+
+---
+
+#### `RootBeer.checkForSuBinary(): boolean`
+
+Scans a curated list of common binary paths (e.g. `/system/bin/su`, `/system/xbin/su`, `/sbin/su`, `/data/local/xbin/su`, etc.) for the presence of the `su` executable. This is a **static file check** — it does not execute `su`.
+
+```typescript
+if (RootBeer.checkForSuBinary()) {
+  console.warn('su binary found on filesystem.');
+}
+```
+
+---
+
+#### `RootBeer.checkForMagiskBinary(): boolean`
+
+Scans common paths for the Magisk binary. Useful as a secondary check because Magisk's systemless root approach can evade package-manager-based detection (`detectRootManagementApps`) if the Magisk Manager APK is uninstalled.
+
+```typescript
+if (RootBeer.checkForMagiskBinary()) {
+  console.warn('Magisk binary present — device likely uses Magisk root.');
+}
+```
+
+---
+
+#### `RootBeer.checkForBinary(binaryName: string): boolean`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `binaryName` | `string` | ✅ | The binary filename to scan for (e.g. `"su"`, `"busybox"`, `"magisk"`). |
+
+Scans the same set of filesystem paths as `checkForSuBinary()` and `checkForMagiskBinary()`, but for an **arbitrary binary name**. Use this for custom checks beyond the preset methods.
+
+```typescript
+// Check for busybox specifically
+const hasBusyBox = RootBeer.checkForBinary('busybox');
+
+// Check for any custom binary
+const hasFridaServer = RootBeer.checkForBinary('frida-server');
+```
+
+---
+
+#### `RootBeer.checkSuExists(): boolean`
+
+Attempts to **execute** `su` using `Runtime.exec()` and returns `true` if the process starts successfully. This is a runtime probe — the most definitive `su` check, but also the most invasive. On a hardened device, this call might be logged by security software.
+
+```typescript
+// Definitive but invasive — su is actually invoked
+if (RootBeer.checkSuExists()) {
+  console.warn('su is executable on this device.');
+}
+```
+
+---
+
+#### `RootBeer.checkForDangerousProps(): boolean`
+
+Reads Android system properties via `getprop` and returns `true` if any of the following dangerous values are set:
+
+| Property | Dangerous Value |
+|---|---|
+| `ro.debuggable` | `1` |
+| `ro.secure` | `0` |
+| `ro.build.type` | `eng` |
+| `ro.build.tags` | `test-keys` |
+
+```typescript
+if (RootBeer.checkForDangerousProps()) {
+  console.warn('Dangerous system properties detected.');
+}
+```
+
+---
+
+#### `RootBeer.checkForRWPaths(): boolean`
+
+Parses `/proc/mounts` and checks whether any paths that should always be read-only on a stock Android device (e.g. `/system`, `/data`) are mounted with write permissions. Read-write system mounts are a strong indicator of root-level filesystem modifications.
+
+```typescript
+if (RootBeer.checkForRWPaths()) {
+  console.warn('System paths are mounted read-write.');
+}
+```
+
+---
+
+## Detection Method Deep Dive
+
+Different checks have different trade-offs. Use this table to choose the right combination for your threat model.
+
+| Method | Technique | Invasiveness | False Positive Risk | Bypass Difficulty |
+|---|---|---|---|---|
+| `isRooted()` | All checks combined | Medium | Low–Medium | Hard |
+| `isRootedWithoutBusyBoxCheck()` | All except BusyBox | Medium | **Lower** | Hard |
+| `detectRootManagementApps()` | Package query | Low | Very Low | Easy (uninstall app) |
+| `detectPotentiallyDangerousApps()` | Package query | Low | Low | Easy (uninstall app) |
+| `detectRootCloakingApps()` | Package query | Low | Very Low | Very Easy (the app hides it) |
+| `detectTestKeys()` | Build property | Very Low | Low | Hard (requires ROM resign) |
+| `checkForSuBinary()` | File path scan | Very Low | Low | Medium (bind mount) |
+| `checkForMagiskBinary()` | File path scan | Very Low | Very Low | Medium (Magisk hide) |
+| `checkForBinary(name)` | File path scan | Very Low | Depends on binary | Medium |
+| `checkSuExists()` | Process execution | **High** | Low | Medium |
+| `checkForDangerousProps()` | `getprop` read | Low | Low | Medium (prop reset) |
+| `checkForRWPaths()` | `/proc/mounts` parse | Very Low | Very Low | Hard |
+
+**Recommended strategy for production apps:**
+
+1. Start with `isRooted()` as your primary gate.
+2. If you need lower false positives, switch to `isRootedWithoutBusyBoxCheck()`.
+3. For high-security applications (banking, DRM), run all 12 checks individually and send the full result object to your backend for server-side evaluation.
+
+---
+
+## Platform Guard Reference
+
+Because the module is registered with `TurboModuleRegistry.getEnforcing`, it **throws** on any platform where it is not registered (iOS, Android Old Architecture, web). Always guard calls:
+
+```typescript
+import { Platform } from 'react-native';
+import { RootBeer } from 'react-native-root-beer';
+
+// ✅ Correct — guarded
+if (Platform.OS === 'android') {
+  const rooted = RootBeer.isRooted();
+}
+
+// ✅ Correct — early return pattern
+function checkDevice(): boolean {
+  if (Platform.OS !== 'android') {
+    return false; // or handle as you see fit
+  }
+  return RootBeer.isRooted();
+}
+
+// ❌ Incorrect — will throw on iOS / web
+const rooted = RootBeer.isRooted();
+```
+
+For TypeScript projects you can create a typed utility:
+
+```typescript
+// utils/security.ts
+import { Platform } from 'react-native';
+import { RootBeer } from 'react-native-root-beer';
+
+/**
+ * Returns `null` on non-Android platforms so callers can
+ * distinguish "not applicable" from "false".
+ */
+export function isDeviceRooted(): boolean | null {
+  if (Platform.OS !== 'android') return null;
+  return RootBeer.isRooted();
+}
+```
+
+---
+
+## Architecture
+
+```
+Consumer App (TypeScript)
+         │
+         │  import { RootBeer } from 'react-native-root-beer'
+         ▼
+  ┌─────────────────────┐
+  │   src/RootBeer.ts   │  Public API object (as const, fully typed)
+  └──────────┬──────────┘
+             │
+             ▼
+  ┌──────────────────────────┐
+  │  src/NativeRootBeer.ts   │  TurboModule Spec (Codegen source of truth)
+  └──────────┬───────────────┘
+             │  React Native Codegen auto-generates ↓
+             ▼
+  ┌────────────────────────────────┐
+  │  NativeRootBeerSpec.kt         │  Abstract Kotlin class (generated)
+  │  (com.rootbeer package)        │
+  └──────────┬─────────────────────┘
+             │  extends
+             ▼
+  ┌────────────────────────────────┐
+  │  RootBeerModule.kt             │  Concrete implementation
+  │  • Registered as TurboModule   │  • lazy-initialises RootBeerLib
+  │  • isTurboModule = true        │  • delegates each method to SDK
+  └──────────┬─────────────────────┘
+             │
+             ▼
+  ┌──────────────────────────────────────────┐
+  │  com.scottyab:rootbeer-lib:0.1.2         │  Android SDK (Maven Central)
+  │  Declared in library's build.gradle      │  Resolved as transitive dep
+  └──────────────────────────────────────────┘
+```
+
+**Key architectural decisions:**
+
+- **`BaseReactPackage`** (not the older `ReactPackage`): The `RootBeerPackage` class extends `BaseReactPackage` — the correct base for New Architecture modules that expose TurboModules.
+- **`isTurboModule = true`** in `ReactModuleInfo`: This opts the module into the TurboModule JSI pathway, bypassing the legacy bridge entirely.
+- **`needsEagerInit = false`**: The native module is only instantiated on first use, not at app startup.
+- **Lazy SDK initialization** (`by lazy`): The `com.scottyab.rootbeer.RootBeer` instance is created once, on first method call, using the `ReactApplicationContext`. This avoids paying the initialization cost if the module is never called.
+- **Codegen spec name** (`codegenConfig.name = "RootBeerSpec"`): The generated spec class is `NativeRootBeerSpec`, and the Java package is `com.rootbeer`, controlled by `codegenConfig.android.javaPackageName`.
+
+---
+
+## Troubleshooting
+
+### Build error: `Cannot find NativeRootBeerSpec`
+
+Codegen has not run yet. This happens when you install the package and try to build without cleaning first.
+
+```bash
+cd android && ./gradlew clean
+cd .. && npx react-native run-android
+```
+
+For Expo:
+
+```bash
+npx expo prebuild --clean --platform android
+npx expo run:android
+```
+
+---
+
+### Build error: `Could not resolve com.scottyab:rootbeer-lib:0.1.2`
+
+Your Gradle build cannot reach Maven Central. Check that `mavenCentral()` is in your root `android/build.gradle` repositories block:
+
+```groovy
+// android/build.gradle
+allprojects {
+  repositories {
+    google()
+    mavenCentral() // ← must be present
+  }
+}
+```
+
+---
+
+### `TurboModuleRegistry.getEnforcing` error at runtime
+
+You called a `RootBeer` method on a non-Android platform, or your app is running in Old Architecture mode.
+
+- **Platform fix:** Wrap all calls in `if (Platform.OS === 'android') { ... }`.
+- **Architecture fix:** Ensure `newArchEnabled=true` in `android/gradle.properties`.
+
+---
+
+### `isRooted()` returns `true` on a production device (false positive)
+
+Some manufacturer ROMs (particularly older Xiaomi, Samsung Knox variants) ship with BusyBox or test-keys. Switch to:
+
+```typescript
+// Exclude BusyBox from the composite check
+const isRooted = RootBeer.isRootedWithoutBusyBoxCheck();
+```
+
+Then run the granular scan to identify the exact triggering check and evaluate whether it represents a real risk for your threat model.
+
+---
+
+### Methods return `false` on a known-rooted emulator
+
+Some AVD (Android Virtual Device) emulators and certain Genymotion configurations don't expose root indicators in the paths RootBeer scans. For reliable testing:
+
+- Use a **physical device** with Magisk or SuperSU installed.
+- Or try `RootBeer.detectTestKeys()` — emulators are almost always signed with test keys.
+
+---
+
+## License
+
+MIT © mr:X