Skip to content

Root Lifecycle & su Gate

Root access is the core capability requirement for raw block device manipulation on Android. fparted enforces a strict, multi-stage startup lifecycle to ensure safety and prevent undefined behavior.

🚦 Startup State Machine

stateDiagram-v2
    [*] --> coldStart
    coldStart --> checkingRootBinary: Probe exact /system/bin/su

    checkingRootBinary --> rootBinaryMissing: File not found / unexecutable
    rootBinaryMissing --> ExitDialog: Show non-dismissible Dialog
    ExitDialog --> [*]: finishAndRemoveTask()

    checkingRootBinary --> requestingRootGrant: /system/bin/su exists
    requestingRootGrant --> rootDenied: Grant denied by root manager
    requestingRootGrant --> rootExecutionFailed: /system/bin/su -c true fails
    requestingRootGrant --> checkingToolchain: Root probe succeeds

    checkingToolchain --> validatingInstalledToolchain: Toolchain manifest found
    checkingToolchain --> selectingCompatibleRelease: No toolchain / corrupted

    selectingCompatibleRelease --> downloading: Fetch Repo A release asset
    downloading --> verifying: Verify SHA-256 & Signature
    verifying --> installing: Extract to files/staging
    installing --> validatingInstalledToolchain: Atomic rename & manifest fsync

    validatingInstalledToolchain --> scanningDisks: Discover hardware block devices
    scanningDisks --> ready: Disks loaded into cache

🔐 Root Contracts

1. Exact Binary Path Gate

  • The gate strictly tests the canonical path: 
    /system/bin/su
  • No fallback to $PATH lookups, /sbin/su, /xbin/su, or Magisk mirror aliases is permitted for the initial gate.

2. Missing-Root Exit Dialog

If /system/bin/su is missing: - A non-dismissible informational dialog is displayed. - The dialog contains exactly one action: Exit. - Dismissal via the back gesture, escape key, or clicking outside is disabled. - Tapping Exit invokes Activity.finishAndRemoveTask() via the platform channel bridge with SystemNavigator.pop() as a fallback. - No network queries, toolchain downloads, or disk discovery are permitted in this state.

3. Separate Grant Probe

  • After verifying /system/bin/su exists, a separate root grant probe is executed: 
    /system/bin/su -c true
  • Root grant denial (exit code 1 / permission rejected by Magisk, KernelSU, or APatch) is reported as a distinct typed state (rootDenied), separate from execution failure (rootExecutionFailed) or missing binaries.
  • Root Managers & Authorization Models:
  • Magisk: Intercepts su invocations dynamically and raises an interactive superuser prompt.
  • KernelSU & Kernel Root Variants (KernelSU, KernelSU-Next, SukiSU, ReSukiSU, APatch): Use kernel profile-based / SuperKey isolation; non-whitelisted apps do not raise interactive prompts upon calling su. The user must manually open their manager app (KernelSU / APatch) and toggle Superuser on for Partition Manager (vn.shadichy.parted).