Skip to content

Debloat your Android TV, install apps, browse and transfer files on it, all from your phone. Just 3 MB, no tracking, no root, no PC.

Take maker-specific protection from the list source's protected.json

jesse-agent-821e41627792eda
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e16f29c..33850b0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -22,7 +22,7 @@ Thanks for helping! Tellyscope is young, so the code and its structure are still
The per-TV lists behind **Debloat** and the Overview's list card live in the [tellyscope-devices](../../../tellyscope-devices) repository, not here; add or fix a list there. When you add a package to a list:
- Say which TV models you tested on, and what changed after disabling it.
-- If disabling it broke anything (launcher, updates, remote, input, HDMI-CEC), put it in the list's keep entries, or propose it for the built-in protected list (`adb/src/main/kotlin/app/tellyscope/adb/Protected.kt`) here.
+- If disabling it broke anything (launcher, updates, remote, input, HDMI-CEC), put it in the list's keep entries. If it must never be stopped or disabled, add it to tellyscope-devices' `lists/protected.json` when only one maker's TVs have it, or propose it for the built-in protected list (`adb/src/main/kotlin/app/tellyscope/adb/Protected.kt`) here when every Android TV, Google TV or Fire TV can have it.
### Using your own lists
diff --git a/README.md b/README.md
index a3e00f5..8764a63 100644
--- a/README.md
+++ b/README.md
@@ -79,7 +79,7 @@ Debloating a TV can break it if done carelessly. Tellyscope keeps to these rules
1. **Disable, never uninstall, what came with the TV.** Built-in apps get `pm disable-user`, which Undo or `pm enable` reverses. Uninstall is offered only for apps you installed (`pm list packages -3`), after a confirm. Tellyscope never runs `pm uninstall --user 0`.
2. **Record before changing.** Before its first change on a TV, Tellyscope notes which apps were already off. Every change goes into that TV's History with an Undo (except uninstalls), and **Restore everything** turns back on only what Tellyscope turned off.
-3. **Protected list.** Apps the TV needs to boot, update, stay on Wi-Fi, show web pages, show its home screen or take input can't be stopped or disabled, with no override. A TV's list can only add warnings, never remove protection. When you switch home screens, the old launcher is turned off only after Home is checked to open the new one.
+3. **Protected list.** Apps the TV needs to boot, update, stay on Wi-Fi, show web pages, show its home screen or take input can't be stopped or disabled, with no override. A TV's list can only add warnings, never remove protection. Packages only one maker's TVs have are protected from tellyscope-devices' `protected.json`, which can only add to the built-in list. When you switch home screens, the old launcher is turned off only after Home is checked to open the new one.
4. **You see it first.** Every change names the apps it touches and asks before it runs.
5. **No root, no exploits.** Only what ADB allows on a stock TV.
6. **Nothing left on the TV.** Two small helpers run from `/data/local/tmp`: one reads app names and icons and is deleted at once, the other runs the Remote and is deleted when the Remote closes.
diff --git a/adb/src/main/kotlin/app/tellyscope/adb/Protected.kt b/adb/src/main/kotlin/app/tellyscope/adb/Protected.kt
index 096031e..6027617 100644
--- a/adb/src/main/kotlin/app/tellyscope/adb/Protected.kt
+++ b/adb/src/main/kotlin/app/tellyscope/adb/Protected.kt
@@ -39,7 +39,6 @@ object Protected {
"com.android.settings" to ProtectedReason.SETTINGS,
"com.android.tv.settings" to ProtectedReason.SETTINGS,
"com.amazon.tv.settings.v2" to ProtectedReason.SETTINGS, // Fire TV
- "org.droidtv.settings" to ProtectedReason.SETTINGS, // Philips
"com.android.vending" to ProtectedReason.PLAY_SERVICES,
"com.google.android.gms" to ProtectedReason.PLAY_SERVICES,
"com.google.android.gsf" to ProtectedReason.PLAY_SERVICES,
@@ -83,6 +82,13 @@ object Protected {
"provision" to ProtectedReason.SETUP_WIZARD,
)
+ /**
+ * Packages only one maker's TVs need, from the list source's `protected.json`, so a new one
+ * ships without an app release. They only add: a package the rules above protect keeps their reason, whatever
+ * this holds, so a list can't take a protection away.
+ */
+ @Volatile var extra: Map<String, ProtectedReason> = emptyMap()
+
/**
* [homePackages] are the device's launchers, read live; they are protected whatever their name.
* A [userApp] (one the user installed) named like a launcher isn't: only the live lookup
@@ -94,6 +100,7 @@ object Protected {
if (CORE.matches(pkg) && !CORE_OK.matches(pkg)) return ProtectedReason.SYSTEM
val lower = pkg.lowercase()
PATTERNS.firstOrNull { (fragment, why) -> fragment in lower && !(userApp && why == ProtectedReason.HOME_SCREEN) }?.let { return it.second }
- return if (UPDATER.containsMatchIn(lower)) ProtectedReason.UPDATES else null
+ if (UPDATER.containsMatchIn(lower)) return ProtectedReason.UPDATES
+ return extra[pkg]
}
}
diff --git a/adb/src/test/kotlin/app/tellyscope/adb/ActionsTest.kt b/adb/src/test/kotlin/app/tellyscope/adb/ActionsTest.kt
index 0a23123..7fe6f9c 100644
--- a/adb/src/test/kotlin/app/tellyscope/adb/ActionsTest.kt
+++ b/adb/src/test/kotlin/app/tellyscope/adb/ActionsTest.kt
@@ -31,6 +31,19 @@ class ActionsTest {
assertEquals(ActionResult.Done(Action.OPEN), Actions(sh).run(Action.STOP, "com.google.android.youtube.tv"))
}
+ /** The list source's protected packages hold for a hand-picked Stop or Disable too, not only Debloat. */
+ @Test fun refusesAPackageTheListProtects() = runTest {
+ val sh = FakeShell(mapOf(home))
+ try {
+ Protected.extra = mapOf("org.droidtv.eum" to ProtectedReason.TV_INPUTS_REMOTE)
+ assertEquals(ActionResult.Refused(ProtectedReason.TV_INPUTS_REMOTE), Actions(sh).run(Action.STOP, "org.droidtv.eum"))
+ assertEquals(ActionResult.Refused(ProtectedReason.TV_INPUTS_REMOTE), Actions(sh).run(Action.DISABLE, "org.droidtv.eum"))
+ assertTrue(sh.ran.none { it.startsWith("pm ") || it.startsWith("am ") })
+ } finally {
+ Protected.extra = emptyMap()
+ }
+ }
+
@Test fun refusesCurrentLauncherWhateverItsName() = runTest {
val sh = FakeShell(mapOf("cmd package resolve-activity" to ok("com.example.customhome/.Home\n")))
assertEquals(ActionResult.Refused(ProtectedReason.HOME_SCREEN), Actions(sh).run(Action.DISABLE, "com.example.customhome"))
diff --git a/adb/src/test/kotlin/app/tellyscope/adb/ProtectedTest.kt b/adb/src/test/kotlin/app/tellyscope/adb/ProtectedTest.kt
index f4a6bf1..ddbd1c5 100644
--- a/adb/src/test/kotlin/app/tellyscope/adb/ProtectedTest.kt
+++ b/adb/src/test/kotlin/app/tellyscope/adb/ProtectedTest.kt
@@ -23,7 +23,6 @@ class ProtectedTest {
@Test fun vendorSettingsAndTheMediaModule() {
assertEquals(ProtectedReason.SETTINGS, Protected.reason("com.amazon.tv.settings.v2"))
- assertEquals(ProtectedReason.SETTINGS, Protected.reason("org.droidtv.settings"))
assertEquals(ProtectedReason.SYSTEM, Protected.reason("com.google.android.providers.media.module"))
}
@@ -65,4 +64,30 @@ class ProtectedTest {
assertNull(Protected.reason("com.sony.dtv.networkapp.wifidirect"))
assertNull(Protected.reason("com.amazon.wifilocker"))
}
+
+ /** One maker's packages come from the list source, not the app. */
+ @Test fun makerPackagesAreProtectedOnlyByTheList() {
+ assertNull(Protected.reason("org.droidtv.eum"))
+ assertNull(Protected.reason("org.droidtv.settings"))
+ try {
+ Protected.extra = mapOf("org.droidtv.eum" to ProtectedReason.TV_INPUTS_REMOTE, "org.droidtv.settings" to ProtectedReason.SETTINGS)
+ assertEquals(ProtectedReason.TV_INPUTS_REMOTE, Protected.reason("org.droidtv.eum"))
+ assertEquals(ProtectedReason.SETTINGS, Protected.reason("org.droidtv.settings"))
+ } finally {
+ Protected.extra = emptyMap()
+ }
+ }
+
+ /** A fork's list can leave a built-in package out or give it another reason; neither takes the protection away. */
+ @Test fun aListCannotTakeABuiltInProtectionAway() {
+ assertEquals(ProtectedReason.SETTINGS, Protected.reason("com.android.settings"))
+ try {
+ Protected.extra = mapOf("com.android.settings" to ProtectedReason.UPDATES, "com.acme.extra" to ProtectedReason.SYSTEM)
+ assertEquals(ProtectedReason.SETTINGS, Protected.reason("com.android.settings"))
+ assertEquals(ProtectedReason.HOME_SCREEN, Protected.reason("com.google.android.tvlauncher"))
+ assertEquals(ProtectedReason.PLAY_SERVICES, Protected.reason("com.google.android.gms"))
+ } finally {
+ Protected.extra = emptyMap()
+ }
+ }
}
diff --git a/app/src/main/java/app/tellyscope/data/DeviceLists.kt b/app/src/main/java/app/tellyscope/data/DeviceLists.kt
index 5f3a09f..936eabc 100644
--- a/app/src/main/java/app/tellyscope/data/DeviceLists.kt
+++ b/app/src/main/java/app/tellyscope/data/DeviceLists.kt
@@ -102,7 +102,7 @@ fun merge(maker: String, lists: List<DeviceList>): DeviceList = DeviceList(
/** A file the index names outside `devices/`, checked against [sha256] like a device file. */
data class ListFile(val file: String, val sha256: String)
-/** [lists] by name (`launchers`, `labels`, `streaming`) and [logos] by logo name; empty on an index from before they moved here. */
+/** [lists] by name (`launchers`, `labels`, `streaming`, `protected`) and [logos] by logo name; empty on an index from before they moved here. */
data class ListIndex(
val commit: String?,
val devices: List<ListEntry>,
@@ -318,20 +318,20 @@ class DeviceLists(
file(entry.file, entry.sha256)?.let { parseList(it.decodeToString(), entry.id) }
/**
- * The launcher, app name and streaming lists the index names, each from cache or the network.
+ * The launcher, app name, streaming and protected lists the index names, each from cache or the network.
* One that can't be had is null in [SharedFiles], so the caller keeps what it has.
*/
suspend fun shared(): SharedFiles {
val lists = index()?.lists.orEmpty()
suspend fun get(name: String) = lists[name]?.let { file(it.file, it.sha256) }?.decodeToString()
- return SharedFiles(get("launchers"), get("labels"), get("streaming"))
+ return SharedFiles(get("launchers"), get("labels"), get("streaming"), get("protected"))
}
/** The lists as last cached, without the network, for the moment before [shared] answers; each only while it matches the cached index. */
suspend fun cachedShared(): SharedFiles = withContext(Dispatchers.IO) {
val lists = File(dir, "index.json").takeIf { it.exists() }?.readText()?.let(::parseIndex)?.lists.orEmpty()
fun read(name: String) = lists[name]?.let { f -> cached(f.file)?.takeIf { sha256(it) == f.sha256 } }?.decodeToString()
- SharedFiles(read("launchers"), read("labels"), read("streaming"))
+ SharedFiles(read("launchers"), read("labels"), read("streaming"), read("protected"))
}
/**
@@ -403,7 +403,7 @@ class DeviceLists(
}
/** The raw text of each shared list; null for one not available. */
-data class SharedFiles(val launchers: String?, val labels: String?, val streaming: String?)
+data class SharedFiles(val launchers: String?, val labels: String?, val streaming: String?, val protected: String? = null)
enum class SourceResult { Ok, NotHttps, Unreachable, NotAList }
diff --git a/app/src/main/java/app/tellyscope/data/Launchers.kt b/app/src/main/java/app/tellyscope/data/Launchers.kt
index 1585f70..652b239 100644
--- a/app/src/main/java/app/tellyscope/data/Launchers.kt
+++ b/app/src/main/java/app/tellyscope/data/Launchers.kt
@@ -2,6 +2,8 @@
package app.tellyscope.data
+import app.tellyscope.adb.Protected
+import app.tellyscope.adb.ProtectedReason
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
@@ -65,18 +67,44 @@ fun parseLabels(text: String): Map<String, String> = try {
emptyMap()
}
-/** The launcher, app name and streaming lists, as [SharedLists] holds them. */
+/** The reasons `protected.json` may give; a list can't claim the home screen or the TV's own states. */
+private val LIST_REASONS = listOf(
+ ProtectedReason.SYSTEM, ProtectedReason.SETTINGS, ProtectedReason.PLAY_SERVICES, ProtectedReason.KEYBOARD,
+ ProtectedReason.TV_INPUTS_REMOTE, ProtectedReason.SETUP_WIZARD, ProtectedReason.UPDATES,
+).associateBy { it.name.lowercase() }
+
+/**
+ * Package to why it stays on, from `protected.json`; its groups (one per maker) are only there for
+ * people reading the file. A reason this app doesn't know still protects, as [ProtectedReason.SYSTEM].
+ * Empty unless it is schema 1; anything under a name that isn't a package is dropped.
+ */
+fun parseProtected(text: String): Map<String, ProtectedReason> = try {
+ val o = jsonObject(text)
+ if (o.optInt("schema") != 1) emptyMap() else buildMap {
+ o.getJSONArray("groups").objectsOrSkip { it.getJSONObject("packages") }.forEach { packages ->
+ for (pkg in packages.keys()) {
+ if (PACKAGE.matches(pkg)) put(pkg, LIST_REASONS[packages.optString(pkg)] ?: ProtectedReason.SYSTEM)
+ }
+ }
+ }
+} catch (_: org.json.JSONException) {
+ emptyMap()
+}
+
+/** The launcher, app name, streaming and protected lists, as [SharedLists] holds them. */
data class Shared(
val launchers: List<KnownLauncher> = emptyList(),
val labels: Map<String, String> = emptyMap(),
val streaming: List<StreamingService> = emptyList(),
+ val protected: Map<String, ProtectedReason> = emptyMap(),
)
/**
* The lists anyone can change without an app release, from the list source next to the debloat
* lists ([DeviceLists]): the last cached copy at launch, then the source's. A list the source
* can't give keeps what was there. The app bundles none, so before the first fetch they are empty;
- * a build with `fixtures/` among its Java resources (the tests) starts from those instead.
+ * a build with `fixtures/` among its Java resources (the tests) starts from those instead. The
+ * protected list goes on to [Protected.extra], on top of the built-in one.
*/
object SharedLists {
private val _state = MutableStateFlow(seed())
@@ -90,7 +118,7 @@ object SharedLists {
/** The cached lists from [lists], then the source's; [fresh] drops the old ones first, for a new source. */
suspend fun load(lists: DeviceLists, fresh: Boolean = false) {
source = lists
- if (fresh) _state.value = seed() else apply(lists.cachedShared())
+ if (fresh) reset(seed()) else apply(lists.cachedShared())
apply(lists.shared())
}
@@ -108,8 +136,15 @@ object SharedLists {
launchers = f.launchers?.let(::parseLaunchers)?.ifEmpty { null } ?: now.launchers,
labels = f.labels?.let(::parseLabels)?.ifEmpty { null } ?: now.labels,
streaming = f.streaming?.let(::parseStreaming)?.ifEmpty { null } ?: now.streaming,
+ protected = f.protected?.let(::parseProtected)?.ifEmpty { null } ?: now.protected,
)
}
+ Protected.extra = _state.value.protected
+ }
+
+ private fun reset(shared: Shared) {
+ _state.value = shared
+ Protected.extra = shared.protected
}
private fun seed() = Shared(
diff --git a/app/src/test/java/app/tellyscope/LaunchersTest.kt b/app/src/test/java/app/tellyscope/LaunchersTest.kt
index 2e9b593..a8746a2 100644
--- a/app/src/test/java/app/tellyscope/LaunchersTest.kt
+++ b/app/src/test/java/app/tellyscope/LaunchersTest.kt
@@ -2,24 +2,35 @@
package app.tellyscope
+import app.tellyscope.adb.Protected
+import app.tellyscope.adb.ProtectedReason
import app.tellyscope.data.ACCESSIBILITY_LAUNCHERS
+import app.tellyscope.data.DeviceLists
+import app.tellyscope.data.LISTS_BASE
import app.tellyscope.data.KnownLauncher
import app.tellyscope.data.SharedLists
import app.tellyscope.data.parseLabels
import app.tellyscope.data.parseLaunchers
+import app.tellyscope.data.parseProtected
import app.tellyscope.ui.RECOMMENDED
+import kotlinx.coroutines.test.runTest
import org.junit.Assert.assertEquals
import org.junit.Assert.assertTrue
+import org.junit.Rule
import org.junit.Test
+import org.junit.rules.TemporaryFolder
import org.junit.runner.RunWith
import org.robolectric.RobolectricTestRunner
import org.robolectric.annotation.Config
import java.io.File
+import java.io.IOException
+import java.security.MessageDigest
/** org.json is Android's, so this runs under Robolectric. */
@RunWith(RobolectricTestRunner::class)
@Config(sdk = [35])
class LaunchersTest {
+ @get:Rule val tmp = TemporaryFolder()
@Test fun theListReadsWhole() {
val text = File("src/test/resources/fixtures/launchers.json").readText()
val launchers = parseLaunchers(text)
@@ -71,4 +82,35 @@ class LaunchersTest {
assertTrue(parseLaunchers(text.replace("\"schema\":1", "\"schema\":2")).isEmpty())
assertTrue(parseLaunchers("{").isEmpty())
}
+
+ /** A list can't claim the home screen or the TV's own states, and a reason this app doesn't know still protects. */
+ @Test fun badProtectedEntriesAreDroppedAndOnlySchemaOneCounts() {
+ val text = """{"schema":1,"groups":[
+ {"name":"Acme","packages":{"com.acme.help":"tv_inputs_remote","com.acme.home":"home_screen","com.acme.new":"some_new_reason","not a package":"system"}},
+ {"name":"No packages"},
+ "not an object"
+ ]}"""
+ assertEquals(
+ mapOf("com.acme.help" to ProtectedReason.TV_INPUTS_REMOTE, "com.acme.home" to ProtectedReason.SYSTEM, "com.acme.new" to ProtectedReason.SYSTEM),
+ parseProtected(text),
+ )
+ assertTrue(parseProtected(text.replace("\"schema\":1", "\"schema\":2")).isEmpty())
+ assertTrue(parseProtected("{").isEmpty())
+ }
+
+ /** The source's `protected.json` reaches [Protected] on top of the built-in list. */
+ @Test fun theProtectedListAddsToTheBuiltInOne() = runTest {
+ val file = """{"schema":1,"groups":[{"name":"Philips","packages":{"org.droidtv.eum":"tv_inputs_remote","com.android.settings":"updates"}}]}""".toByteArray()
+ val sha = MessageDigest.getInstance("SHA-256").digest(file).joinToString("") { "%02x".format(it) }
+ val index = """{"schema":1,"devices":[],"lists":{"protected":{"file":"lists/protected.json","sha256":"$sha"}}}""".toByteArray()
+ val served = mapOf("index.json" to index, "lists/protected.json" to file)
+ try {
+ SharedLists.load(DeviceLists(tmp.newFolder()) { url -> served[url.removePrefix(LISTS_BASE)] ?: throw IOException("404 $url") }, fresh = true)
+ assertEquals(ProtectedReason.TV_INPUTS_REMOTE, Protected.reason("org.droidtv.eum"))
+ assertEquals(ProtectedReason.SETTINGS, Protected.reason("com.android.settings"))
+ } finally {
+ // Back to the seed lists, for the tests after this one.
+ SharedLists.load(DeviceLists(tmp.newFolder()) { throw IOException("offline") }, fresh = true)
+ }
+ }
}