v2.4.0: the in-app Android API bridge, the defensible permission profile, and the user startup hook

AGENTS.md

@@ -334,8 +334,39 @@ Agreed plan, all phases to be delivered. Status is tracked below and updated as
   a theme that declares `terminalBg`, `terminalText` and `colorPrimary` themes the whole
   app including the terminal.
 
+## bionic gates static executables on the TLS segment, and proot-executed binaries must not be static
+
+- **A static NDK executable can abort on start with `executable's TLS segment is
+  underaligned: alignment is 8 (skew 0), needs to be at least 64 for ARM64 Bionic`.**
+  bionic's static-TLS layout check (StaticTlsLayout) validates `PT_TLS` p_align and
+  vaddr skew, and the NDK's plain static link emits 8. The 16 KB-era NDK makes the
+  static path a dead end for proot-executed binaries on top of that: bionic's own
+  `.bss` is 16 KB aligned, and a proot-loaded ELF must keep 4 KB LOAD segments or it
+  breaks 4 KB-page devices (`-z max-page-size` cannot down-align input sections).
+- **The fix is to link dynamically, as `build-mosh.sh` does for the mosh client:**
+  bionic's shared `libc.so`, `INTERP /system/bin/linker64` (the guest reaches both
+  through the `/system` bind), 4 KB LOADs, and the dynamic linker's own TLS setup
+  instead of the static gate. `build-redterm-api.sh` builds the API helper this way
+  and verifies every LOAD stays ≤ 4 KB; the mosh build pins the same check.
+- `build-proot.sh` still patches the static proot's `PT_TLS` (aarch64) / links the
+  32-byte `.ld` (armv7a), because proot is shipped as a static `libproot.so`; that is
+  the same gate handled per-binary, and the rule is *dynamic unless you own the ELF's
+  TLS alignment yourself*.
+
 ## A shell file is run, not read
 
+- **An `exec` that continues across lines dies at the first line that ends without a
+  backslash, and the lines after it never run.** The proot launcher's api bind was emitted
+  on its own line between the ordinary binds and the guest command: the `exec proot …`
+  statement ended at the ordinary-binds line (no continuation), so the api bind and the
+  command became orphan lines the shell never executed — proot started with the default
+  shell and no api bind, the app log reported the bridge on, and the launcher *file*
+  contained the perfectly correct line. Read-back of a generated script proves what was
+  written, not what the shell will execute: when a generated line feeds a multi-line
+  `exec`, the test has to pin the logical line (same line as its neighbours, ends in
+  `\`), the way `ProotLaunchTest` now does. And a unit test that asserts the api bind
+  *appears somewhere* in the script passed on every build that carried this bug.
+
 - **Quote `%` in anything written into a shell.** Bash does not treat a leading `%` as an
   ordinary character: `%1`, `%?` and `%T` are *job specifiers*, and an unquoted one is
   executed as `fg`. `HISTFMT=%F %T` — one assignment and one word, quotes dropped in a

app/build.gradle.kts

@@ -14,8 +14,8 @@ android {
         applicationId = "com.redtermapp"
         minSdk = 24
         targetSdk = 37
-        versionCode = 7
-        versionName = "2.3.1"
+        versionCode = 8
+        versionName = "2.4.0"
     }
 
     signingConfigs {
@@ -75,6 +75,7 @@ android {
 
 dependencies {
     implementation("androidx.core:core-ktx:1.19.1")
+    implementation("androidx.work:work-runtime:2.12.0")
     implementation("androidx.lifecycle:lifecycle-service:2.11.0")
     implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.11.0")
     implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.11.0")

app/src/main/AndroidManifest.xml

@@ -11,7 +11,8 @@
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
     <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
     <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
-    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="28" />
+    <uses-permission android:name="android.permission.WRITE_SETTINGS"
+        tools:ignore="ProtectedPermissions" />
     <!--
         Backups live in shared storage (/sdcard/RedTerm) specifically so they
         survive uninstalling the app; Android wipes app-specific storage on
@@ -25,6 +26,32 @@
         android:name="android.permission.MANAGE_EXTERNAL_STORAGE"
         tools:ignore="ScopedStorage" />
 
+    <!--
+        Termux:API bridge. This build declares only ACCESS_WIFI_STATE for it:
+        reading the Wi-Fi connection and the scan list. The SSID is masked by
+        the OS unless a location grant is present, and this build deliberately
+        does not declare the location / SMS / phone / call-log / contacts /
+        camera / microphone / phone-state / write-settings / wallpaper /
+        infrared / NFC / biometric permissions. A terminal that ships the whole
+        trojan-like union of them is exactly what Play Protect flags, so the
+        app's static permission profile is kept to the defensible core (the
+        2.3.1 set, plus Wi-Fi state, plus all-files access for its /sdcard
+        backups). A bridge command that needs a permission not declared here
+        answers with an honest "not available in this build" (the gate checks
+        the declared set), not a dead pipe.
+    -->
+    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
+
+    <!--
+        Hardware advertisement only (required=false): a device without the
+        radio can still install and use everything else. No permission is
+        declared for it, so the bridge commands that would need one degrade
+        to "not available in this build" in a build that omits that grant.
+    -->
+    <uses-feature
+        android:name="android.hardware.telephony"
+        android:required="false" />
+
     <application
         android:name=".RedTermApp"
         android:allowBackup="true"
@@ -135,10 +162,59 @@
             android:exported="false"
             android:theme="@style/Theme.RedTermApp" />
 
+         <activity
+             android:name=".ui.BashTemplatesActivity"
+             android:exported="false"
+             android:theme="@style/Theme.RedTermApp" />
+
+        <!--
+            The API UI hosts: transparent activities a guest request can
+            block on. They show exactly one dialog each (a text input, a
+            picker, an NFC reader, a biometric prompt) and post the answer
+            back to the waiting request thread, then finish.
+        -->
         <activity
-            android:name=".ui.BashTemplatesActivity"
+            android:name=".util.api.ui.ApiDialogActivity"
             android:exported="false"
-            android:theme="@style/Theme.RedTermApp" />
+            android:taskAffinity=""
+            android:excludeFromRecents="true"
+            android:theme="@style/Theme.RedTermApp.Transparent" />
+
+        <activity
+            android:name=".util.api.ui.ApiNfcActivity"
+            android:exported="false"
+            android:taskAffinity=""
+            android:excludeFromRecents="true"
+            android:theme="@style/Theme.RedTermApp.Transparent" />
+
+        <activity
+            android:name=".util.api.ui.ApiSafGrantActivity"
+            android:exported="false"
+            android:taskAffinity=""
+            android:excludeFromRecents="true"
+            android:theme="@style/Theme.RedTermApp.Transparent" />
+
+        <activity
+            android:name=".util.api.ui.ApiBiometricActivity"
+            android:exported="false"
+            android:taskAffinity=""
+            android:excludeFromRecents="true"
+            android:theme="@style/Theme.RedTermApp.Transparent" />
+
+        <activity
+            android:name=".util.api.ui.ApiSpeechActivity"
+            android:exported="false"
+            android:taskAffinity=""
+            android:excludeFromRecents="true"
+            android:theme="@style/Theme.RedTermApp.Transparent" />
+
+        <activity
+            android:name=".util.api.ui.ApiCameraActivity"
+            android:exported="false"
+            android:taskAffinity=""
+            android:excludeFromRecents="true"
+            android:theme="@style/Theme.RedTermApp.Transparent" />
+
 
         <service
             android:name=".ui.QuickSettingsTile"

app/src/main/java/com/redtermapp/RedTermApp.kt

@@ -22,8 +22,12 @@ class RedTermApp : Application() {
         }
         com.github.anrwatchdog.ANRWatchDog().start()
         // Before anything can post a completion toast, so "is anything on screen"
-        // is answered for every activity rather than the few that remember to ask.
+        // is answered by every activity rather than the few that remember to ask.
         com.redtermapp.util.Notifier.trackLifecycles(this)
+        // The termux:API bridge: guest sessions reach it over an abstract Unix
+        // socket while the app's process is up; a dead process reads as "the
+        // app is not running", which the guest helper reports honestly.
+        com.redtermapp.util.api.ApiSocket.start(this)
         createNotificationChannel()
         loadRootfsCatalogue()
         verifyMoshNative()

app/src/main/java/com/redtermapp/distro/DistroRunner.kt

@@ -55,15 +55,35 @@ class DistroRunner(private val context: Context) {
         }
         File(rootfsDir, "tmp").mkdirs()
         installer.refreshNetworkConfig(distroName)
+        val apiDir = com.redtermapp.util.api.ApiHelper.ensureInstalled(context)
+        com.redtermapp.util.api.ApiHelper.installGuestScripts(context, rootfsDir)
+        if (apiDir != null) {
+            com.redtermapp.util.AppLog.i(context, "api-bridge", "on: helper bound at ${com.redtermapp.util.api.ApiHelper.GUEST_BIND_TARGET} (one-shot $distroName)")
+        } else {
+            com.redtermapp.util.AppLog.w(context, "api-bridge", "off: no API helper available; the bridge is disabled for $distroName")
+        }
         val launcher = ProotLaunch.writeLauncher(
             context = context,
             rootfsDir = rootfsDir,
             startInner = "/root",
             command = command,
             // Its own script: sharing launch.sh with the terminal meant a
             // background update could rewrite the file the terminal was starting.
-            scriptName = "command-run.sh"
+            scriptName = "command-run.sh",
+            apiHostDir = apiDir?.absolutePath
         )
+        // Same read-back as the terminal path: the bridge's two ends plus the
+        // exact bind line proot will receive, so a dead bridge is diagnosable
+        // from the log alone.
+        if (apiDir != null) {
+            val target = com.redtermapp.util.api.ApiHelper.GUEST_BIND_TARGET
+            val bindLine = launcher.readLines().firstOrNull { it.contains(target) }
+            val helperFile = File(apiDir, com.redtermapp.util.api.ApiHelper.BINARY_NAME)
+            com.redtermapp.util.AppLog.i(
+                context, "api-bridge",
+                "launcher: '${bindLine?.trim() ?: "NO BIND LINE"}'; host helper present=${helperFile.isFile}, guest target present=${File(rootfsDir, "usr/local/redterm").isDirectory} (one-shot $distroName)"
+            )
+        }
         return try {
             val process = ProcessBuilder("/system/bin/sh", launcher.absolutePath)
                 .redirectErrorStream(true)

app/src/main/java/com/redtermapp/distro/DistroSetup.kt

@@ -745,6 +745,22 @@ object DistroSetup {
             append("fi\n")
             append(staleLockRepair)
             append("unset ENV\n")
+            // The user's persistent startup hook, kept separate from this
+            // generated file: RedTerm rewrites this one on every new session,
+            // so a hand edit here would not survive, but /root/.startup.local
+            // is user-managed and persists across sessions and updates. It
+            // runs only for interactive sessions — the launcher sets
+            // REDTERM_INTERACTIVE_SESSION on the interactive tail and never on
+            // one-shot commands — and as a separate process, so a failing or
+            // exiting hook cannot end the terminal session: a non-zero exit is
+            // reported, not fatal. Absent file is a silent no-op.
+            append("if [ -n \"\$REDTERM_INTERACTIVE_SESSION\" ] && [ -f /root/.startup.local ]; then\n")
+            append("    /bin/sh /root/.startup.local\n")
+            append("    hook_status=\$?\n")
+            append("    if [ \"\$hook_status\" -ne 0 ]; then\n")
+            append("        echo \"RedTerm: /root/.startup.local reported an error (exit \$hook_status) — continuing the session\"\n")
+            append("    fi\n")
+            append("fi\n")
             append("if command -v bash >/dev/null 2>&1; then\n")
             append("    exec bash -i\n")
             append("fi\n")

app/src/main/java/com/redtermapp/distro/ProotLaunch.kt

@@ -36,8 +36,15 @@ object ProotLaunch {
         startInner: String? = null,
         command: String? = null,
         scriptName: String = "launch.sh",
-        mergeStderr: Boolean = true
+        mergeStderr: Boolean = true,
+        apiHostDir: String? = null
     ): File {
+        // The guest-side end of the bind must exist in the rootfs, as
+        // proot-distro creates its fake /proc and /sys targets: a bind whose
+        // target is missing is one proot cannot materialise.
+        if (apiHostDir != null) {
+            ensureGuestBindTarget(rootfsDir, com.redtermapp.util.api.ApiHelper.GUEST_BIND_TARGET)
+        }
         val out = File(context.filesDir, scriptName)
         out.parentFile?.mkdirs()
         out.writeText(
@@ -47,7 +54,8 @@ object ProotLaunch {
                 hasLoader32 = File("${context.applicationInfo.nativeLibraryDir}/libproot-loader32.so").exists(),
                 startInner = startInner,
                 command = command,
-                mergeStderr = mergeStderr
+                mergeStderr = mergeStderr,
+                apiHostDir = apiHostDir
             )
         )
         out.setExecutable(true, true)
@@ -61,15 +69,17 @@ object ProotLaunch {
         hasLoader32: Boolean,
         startInner: String? = null,
         command: String? = null,
-        mergeStderr: Boolean = true
+        mergeStderr: Boolean = true,
+        apiHostDir: String? = null
     ): String {
         return buildScriptText(
             nativeLibDir = nativeLibDir,
             rootfsPath = rootfsPath,
             hasLoader32 = hasLoader32,
             startInner = startInner,
             command = command,
-            mergeStderr = mergeStderr
+            mergeStderr = mergeStderr,
+            apiHostDir = apiHostDir
         )
     }
 
@@ -79,7 +89,8 @@ object ProotLaunch {
         hasLoader32: Boolean,
         startInner: String?,
         command: String?,
-        mergeStderr: Boolean
+        mergeStderr: Boolean,
+        apiHostDir: String?
     ): String {
         val prootBin = "$nativeLibDir/libproot.so"
         val prootLoader = "$nativeLibDir/libproot-loader.so"
@@ -92,6 +103,28 @@ object ProotLaunch {
         // middle of an SFTP packet stream desynchronises it permanently. Callers
         // that speak a protocol turn this off and read stderr themselves.
         val redirect = if (mergeStderr) " 2>&1" else ""
+        // The API helper's directory, when the bridge is on for this session:
+        // bound at a path of its own, so the bind never hides a directory the
+        // distro ships (which is what a bind onto /usr/local/bin would do).
+        //
+        // One argument, `host:guest`: the proot this app bundles is the
+        // termux fork, whose -b splits its single argument on the first colon
+        // (handle_option_b in termux/proot). Upstream proot's two-argument form
+        // does not exist there — the second word is read as the *command to
+        // execute*, proot tries to exec it inside the rootfs, fails, and the
+        // session dies 127 before any shell starts. proot-distro, the
+        // reference user of this fork, uses only the colon form.
+        //
+        // It must also stay on the *same logical line* as the other binds: the
+        // exec statement continues across lines only through trailing
+        // backslashes, and a newline here ends the exec at the BOUND_PATHS
+        // line, so the api bind and the guest command become orphan lines
+        // that never run. Leading space, no newline — a long line is what
+        // makes it one command.
+        val apiBind =
+            if (apiHostDir != null) {
+                " -b ${quoteForShell("$apiHostDir:${com.redtermapp.util.api.ApiHelper.GUEST_BIND_TARGET}")}"
+            } else ""
         val tail = if (command == null) {
             "/system/bin/sh -i" + redirect
         } else {
@@ -111,11 +144,25 @@ object ProotLaunch {
             "/system/bin/sh -c ${quoteForShell(inner)}" + redirect
         }
 
+        // The interactive session is the only place the user's persistent
+        // startup hook may run: a one-shot command must not absorb the hook's
+        // output or side effects. The marker is set only on the interactive
+        // tail; the generated /root/.startup reads it to decide whether to
+        // run /root/.startup.local (see DistroSetup.buildStartupScript).
+        val interactiveExport =
+            if (command == null) "export REDTERM_INTERACTIVE_SESSION=1\n" else ""
+
         val script = """#!/system/bin/sh
 umask 022
 export HOME=/root
 export PATH=/system/bin:/system/xbin:/bin:/sbin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
 export ENV=/root/.startup
+$interactiveExport
+# The host path of this rootfs, carried into the guest so the API helper
+# can attach it to every request: the app process opens guest paths
+# through this directory, and without the origin it cannot tell which
+# rootfs a path came from.
+export REDTERM_ROOTFS_HOST="$rp"
 export TERM=xterm-256color
 export COLORTERM=truecolor
 if command -v locale >/dev/null 2>&1 && locale -a 2>/dev/null | grep -qi '^C\.utf-\?8$'; then
@@ -145,7 +192,7 @@ mkdir -p "$rp/tmp"
 # the hard way: an inference from a stand-in environment is not a measurement of
 # the real one.
 exec $prootBin -0 -L -r "$rp" -w ${startInner ?: "/root"} --link2symlink --sysvipc --kill-on-exit \
-${BOUND_PATHS.joinToString(" ") { "-b $it" }} \
+${BOUND_PATHS.joinToString(" ") { "-b $it" }}${apiBind} \
     $tail
 """
         return script
@@ -175,4 +222,13 @@ ${BOUND_PATHS.joinToString(" ") { "-b $it" }} \
     val BOUND_PATHS: List<String> = BOUND_DIRS + BOUND_FILES
 
     fun deviceAbi(): String = Build.SUPPORTED_ABIS.firstOrNull() ?: "arm64-v8a"
+
+    /**
+     * Creates a guest-side bind target inside [rootfsDir] so a proot `-b`
+     * pointing at it can materialise. Mirrors proot-distro's `mkdir -p` of
+     * its fake /proc and /sys targets before every launch.
+     */
+    fun ensureGuestBindTarget(rootfsDir: File, target: String) {
+        File(rootfsDir, target.removePrefix("/")).mkdirs()
+    }
 }