tcl-fw 3.0.0__tar.gz

tcl_fw-3.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tcl_fw-3.0.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: tcl-fw
+Version: 3.0.0
+Summary: Pull and decrypt official TCL (MediaTek) FOTA firmware — flashable service packages, fully offline.
+Author: vehoelite, Littlenine Ennea
+License: MIT
+Project-URL: Homepage, https://github.com/vehoelite/tcl-fota-tool
+Project-URL: Credit, https://github.com/LittlenineEnnea
+Keywords: tcl,fota,firmware,mediatek,android,mbn,decrypt,scatter
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.0
+Requires-Dist: pycryptodome>=3.20
+Provides-Extra: gui
+Requires-Dist: PySide6>=6.6; extra == "gui"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pyinstaller>=6.0; extra == "dev"
+Requires-Dist: PySide6>=6.6; extra == "dev"
+Dynamic: license-file
+
+# tcl-fw
+
+**Pull and decrypt official TCL (MediaTek) firmware — flashable service packages, fully offline.**
+
+`tcl-fw` talks to TCL's own FOTA download servers the way the on-device updater
+does (no Google, no account, no dongle), lists a device's complete factory
+"service" fileset, streams the plaintext partitions, and **AES-decrypts** the
+small partitions that ship inside an encrypted 4 MiB header — producing clean,
+flashable images (`lk.img`, `boot.img`, `vbmeta.img`, `preloader_*.bin`, the
+scatter, …).
+
+> ### Credit
+> The header-decryption scheme that makes this tool possible — **AES-128-ECB
+> with a universal key recovered from `sugar_otu_r.dll`** — was cracked by
+> **[Littlenine Ennea](https://github.com/LittlenineEnnea)**. Mode 4 (full-image
+> decryption) exists entirely because of that work. Thank you.
+
+Works on TCL-made Android devices (TCL, REVVL, Alcatel).
+
+---
+
+## Install
+
+```bash
+pip install tcl-fw          # CLI only
+pip install "tcl-fw[gui]"   # CLI + desktop app (PySide6)
+```
+
+Or grab the standalone `tcl-fw` / `tcl-fw.exe` (CLI) or `tcl-fw-gui.exe`
+(desktop app) from
+[Releases](https://github.com/vehoelite/tcl-fota-tool/releases) — no Python needed.
+
+## Desktop app
+
+Prefer clicking to typing? Launch the GUI:
+
+```bash
+tcl-fw-gui        # or:  python -m tcl_fw_gui
+```
+
+Pick (or **Detect**) a device → **Load** to see every partition with real sizes
+→ tick what you want → **Pull**. Per-partition progress, live decrypt log, and
+SHA-1 verification, all over the exact same backend as the CLI. On Windows the
+GUI uses the native `adb`, so **Detect phone** works without any usbipd/WSL
+plumbing.
+
+## Quickstart
+
+```bash
+# Plug in a phone with USB debugging on — tcl-fw reads the curef itself:
+tcl-fw pull
+
+# …or name the device explicitly:
+tcl-fw list  T704SP-EAUHUS12-V          # see every partition, size, name
+tcl-fw pull  T704SP-EAUHUS12-V          # download + decrypt the whole package
+tcl-fw pull  T704SP-EAUHUS12-V --small  # just the small parts (lk/preloader/… fast)
+tcl-fw pull  T704SP-EAUHUS12-V --only lk,boot,vbmeta
+tcl-fw decrypt some_header.bin          # decrypt one local header blob
+```
+
+Find your curef on a handset:
+
+```bash
+adb shell getprop ro.tct.curef
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `tcl-fw pull [curef]` | Download + decrypt a device's service package into flashable images. Auto-detects the curef from a plugged-in phone if omitted. `--small`, `--only p1,p2`, `--out DIR`, `--no-verify`. |
+| `tcl-fw list [curef]` | Resolve a device and list every partition: name, real size, and whether it comes from the body or the encrypted header. |
+| `tcl-fw decrypt <blob>` | Decrypt a single local encrypted-header blob and name it by content. |
+| `tcl-fw devices [--detect]` | List known devices, or probe for a connected phone. |
+
+## How it works
+
+TCL's FOTA server delivers each partition in one of two ways, and `tcl-fw`
+handles both automatically:
+
+- **Large partitions** (`super`, `system`, `vendor`, `boot`, `md1img`, …) — the
+  plaintext **body** *is* the image; it's streamed straight to disk (with resume
+  and SHA-1 verification against the server's `checksum.php`).
+- **Small partitions** (`lk`, `preloader`, `tee`/`atf`, `vbmeta`, `spmfw`,
+  `scatter`, …) — the body is empty; the real image lives inside an encrypted
+  ~4 MiB header fetched from `encrypt_header.php`. That blob is **AES-128-ECB**
+  with the single universal key
+
+  ```
+  KEY = ascii( md5("TeleExtTest" + "t0523" + "jP7GHdmuBz").hexdigest()[:16] )
+      = e26baba108b08a28
+  ```
+
+  The header is padded with a constant filler block, which `tcl-fw` detects and
+  trims to recover the exact image.
+
+Partitions are named **authoritatively** from the server: the `check_new.php`
+manifest is joined to the `.sca` scatter's `rename_prefix → file_name` map, so
+you get real names, not guesses. When the scatter is unavailable, images are
+identified by content (MTK GFH partition name, ext4 volume label, AVB/boot/dtbo
+magic).
+
+## Output
+
+```
+pkg_<curef>/
+  lk.img  boot.img  vbmeta.img  super.img  preloader_*.bin  …
+  <device>.sca            # the flash-tool scatter
+  manifest.json           # what was pulled, sizes, checksum results
+```
+
+Feed these to SP Flash Tool, `fastboot`, or `mtkclient`.
+
+## Related — Image Anarchy
+
+Pulled a package and want to flash, repack, or explore it? Check out
+**[Image Anarchy](https://github.com/vehoelite/image-anarchy)** — a companion
+toolkit for working with Android firmware images. `tcl-fw` gets you the clean,
+named partitions; Image Anarchy helps you do something with them.
+
+## Legal / ethical use
+
+This tool downloads firmware that TCL's own servers serve publicly, for the
+purpose of repairing, restoring, or inspecting **a device you own**. It uses no
+exploit against the device and asks the servers only for what the on-device
+updater already requests. Respect your local laws and TCL's terms.
+
+## Credits
+
+- **[Littlenine Ennea](https://github.com/LittlenineEnnea)** — cracked the
+  AES-128-ECB header-decryption scheme and the universal key; the reference
+  implementation lives in [`mode4/tcl-fw.py`](mode4/tcl-fw.py). Mode 4 is theirs.
+- **[vehoelite](https://github.com/vehoelite)** — the original `tcl-fota-tool`
+  FOTA protocol client (check/download signing, fileset parsing), preserved in
+  [`legacy/`](legacy/), and the companion
+  [Image Anarchy](https://github.com/vehoelite/image-anarchy) firmware toolkit.
+- Predecessor protocol research: `mbirth/tcl_ota_check`, `thurask/bbarchivist`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

tcl_fw-3.0.0/README.md

@@ -0,0 +1,141 @@
+# tcl-fw
+
+**Pull and decrypt official TCL (MediaTek) firmware — flashable service packages, fully offline.**
+
+`tcl-fw` talks to TCL's own FOTA download servers the way the on-device updater
+does (no Google, no account, no dongle), lists a device's complete factory
+"service" fileset, streams the plaintext partitions, and **AES-decrypts** the
+small partitions that ship inside an encrypted 4 MiB header — producing clean,
+flashable images (`lk.img`, `boot.img`, `vbmeta.img`, `preloader_*.bin`, the
+scatter, …).
+
+> ### Credit
+> The header-decryption scheme that makes this tool possible — **AES-128-ECB
+> with a universal key recovered from `sugar_otu_r.dll`** — was cracked by
+> **[Littlenine Ennea](https://github.com/LittlenineEnnea)**. Mode 4 (full-image
+> decryption) exists entirely because of that work. Thank you.
+
+Works on TCL-made Android devices (TCL, REVVL, Alcatel).
+
+---
+
+## Install
+
+```bash
+pip install tcl-fw          # CLI only
+pip install "tcl-fw[gui]"   # CLI + desktop app (PySide6)
+```
+
+Or grab the standalone `tcl-fw` / `tcl-fw.exe` (CLI) or `tcl-fw-gui.exe`
+(desktop app) from
+[Releases](https://github.com/vehoelite/tcl-fota-tool/releases) — no Python needed.
+
+## Desktop app
+
+Prefer clicking to typing? Launch the GUI:
+
+```bash
+tcl-fw-gui        # or:  python -m tcl_fw_gui
+```
+
+Pick (or **Detect**) a device → **Load** to see every partition with real sizes
+→ tick what you want → **Pull**. Per-partition progress, live decrypt log, and
+SHA-1 verification, all over the exact same backend as the CLI. On Windows the
+GUI uses the native `adb`, so **Detect phone** works without any usbipd/WSL
+plumbing.
+
+## Quickstart
+
+```bash
+# Plug in a phone with USB debugging on — tcl-fw reads the curef itself:
+tcl-fw pull
+
+# …or name the device explicitly:
+tcl-fw list  T704SP-EAUHUS12-V          # see every partition, size, name
+tcl-fw pull  T704SP-EAUHUS12-V          # download + decrypt the whole package
+tcl-fw pull  T704SP-EAUHUS12-V --small  # just the small parts (lk/preloader/… fast)
+tcl-fw pull  T704SP-EAUHUS12-V --only lk,boot,vbmeta
+tcl-fw decrypt some_header.bin          # decrypt one local header blob
+```
+
+Find your curef on a handset:
+
+```bash
+adb shell getprop ro.tct.curef
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `tcl-fw pull [curef]` | Download + decrypt a device's service package into flashable images. Auto-detects the curef from a plugged-in phone if omitted. `--small`, `--only p1,p2`, `--out DIR`, `--no-verify`. |
+| `tcl-fw list [curef]` | Resolve a device and list every partition: name, real size, and whether it comes from the body or the encrypted header. |
+| `tcl-fw decrypt <blob>` | Decrypt a single local encrypted-header blob and name it by content. |
+| `tcl-fw devices [--detect]` | List known devices, or probe for a connected phone. |
+
+## How it works
+
+TCL's FOTA server delivers each partition in one of two ways, and `tcl-fw`
+handles both automatically:
+
+- **Large partitions** (`super`, `system`, `vendor`, `boot`, `md1img`, …) — the
+  plaintext **body** *is* the image; it's streamed straight to disk (with resume
+  and SHA-1 verification against the server's `checksum.php`).
+- **Small partitions** (`lk`, `preloader`, `tee`/`atf`, `vbmeta`, `spmfw`,
+  `scatter`, …) — the body is empty; the real image lives inside an encrypted
+  ~4 MiB header fetched from `encrypt_header.php`. That blob is **AES-128-ECB**
+  with the single universal key
+
+  ```
+  KEY = ascii( md5("TeleExtTest" + "t0523" + "jP7GHdmuBz").hexdigest()[:16] )
+      = e26baba108b08a28
+  ```
+
+  The header is padded with a constant filler block, which `tcl-fw` detects and
+  trims to recover the exact image.
+
+Partitions are named **authoritatively** from the server: the `check_new.php`
+manifest is joined to the `.sca` scatter's `rename_prefix → file_name` map, so
+you get real names, not guesses. When the scatter is unavailable, images are
+identified by content (MTK GFH partition name, ext4 volume label, AVB/boot/dtbo
+magic).
+
+## Output
+
+```
+pkg_<curef>/
+  lk.img  boot.img  vbmeta.img  super.img  preloader_*.bin  …
+  <device>.sca            # the flash-tool scatter
+  manifest.json           # what was pulled, sizes, checksum results
+```
+
+Feed these to SP Flash Tool, `fastboot`, or `mtkclient`.
+
+## Related — Image Anarchy
+
+Pulled a package and want to flash, repack, or explore it? Check out
+**[Image Anarchy](https://github.com/vehoelite/image-anarchy)** — a companion
+toolkit for working with Android firmware images. `tcl-fw` gets you the clean,
+named partitions; Image Anarchy helps you do something with them.
+
+## Legal / ethical use
+
+This tool downloads firmware that TCL's own servers serve publicly, for the
+purpose of repairing, restoring, or inspecting **a device you own**. It uses no
+exploit against the device and asks the servers only for what the on-device
+updater already requests. Respect your local laws and TCL's terms.
+
+## Credits
+
+- **[Littlenine Ennea](https://github.com/LittlenineEnnea)** — cracked the
+  AES-128-ECB header-decryption scheme and the universal key; the reference
+  implementation lives in [`mode4/tcl-fw.py`](mode4/tcl-fw.py). Mode 4 is theirs.
+- **[vehoelite](https://github.com/vehoelite)** — the original `tcl-fota-tool`
+  FOTA protocol client (check/download signing, fileset parsing), preserved in
+  [`legacy/`](legacy/), and the companion
+  [Image Anarchy](https://github.com/vehoelite/image-anarchy) firmware toolkit.
+- Predecessor protocol research: `mbirth/tcl_ota_check`, `thurask/bbarchivist`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

tcl_fw-3.0.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tcl-fw"
+version = "3.0.0"
+description = "Pull and decrypt official TCL (MediaTek) FOTA firmware — flashable service packages, fully offline."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "vehoelite" },
+    { name = "Littlenine Ennea" },
+]
+keywords = ["tcl", "fota", "firmware", "mediatek", "android", "mbn", "decrypt", "scatter"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13.0",
+    "pycryptodome>=3.20",
+]
+
+[project.optional-dependencies]
+gui = ["PySide6>=6.6"]
+dev = ["pytest>=8.0", "pyinstaller>=6.0", "PySide6>=6.6"]
+
+[project.urls]
+Homepage = "https://github.com/vehoelite/tcl-fota-tool"
+Credit = "https://github.com/LittlenineEnnea"
+
+[project.scripts]
+tcl-fw = "tcl_fw.cli:app"
+
+[project.gui-scripts]
+tcl-fw-gui = "tcl_fw_gui:main"
+
+[tool.setuptools]
+packages = ["tcl_fw", "tcl_fw_gui"]
+
+[tool.setuptools.package-data]
+tcl_fw = ["data/*.json"]

tcl_fw-3.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tcl_fw-3.0.0/tcl_fw/__init__.py

@@ -0,0 +1,16 @@
+"""
+tcl-fw — pull and decrypt official TCL (MediaTek) FOTA firmware.
+
+A firmware puller + .mbn header decryptor for TCL-made Android devices
+(TCL, REVVL, Alcatel). Talks to TCL's own FOTA download servers (no Google,
+no account), streams the plaintext bodies, and AES-decrypts the small
+partitions that ship inside an encrypted 4 MiB header — producing a clean,
+flashable service package fully offline.
+
+The header-decryption scheme (AES-128-ECB, universal key) was cracked by
+Littlenine Ennea <https://github.com/LittlenineEnnea>; mode 4 exists because
+of that work. See crypto.py.
+"""
+
+__version__ = "3.0.0"
+__all__ = ["__version__"]

tcl_fw-3.0.0/tcl_fw/__main__.py

@@ -0,0 +1,5 @@
+"""Enable `python -m tcl_fw`."""
+from .cli import app
+
+if __name__ == "__main__":
+    app()

tcl_fw-3.0.0/tcl_fw/adb.py

@@ -0,0 +1,99 @@
+"""
+adb.py — read a plugged-in TCL phone's identity so the user types nothing.
+
+The whole point of "auto-CUREF": if a phone is connected with USB debugging on,
+we can read its curef (and firmware version) directly, then let fota.discover()
+turn that into a tv/fw_id. No manual lookup, no dongle.
+
+Finds adb from (in order): the TCL_FW_ADB env var, a bundled platform-tools/
+next to the package, or the system PATH.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class Device:
+    serial: str
+    curef: Optional[str] = None
+    fv: Optional[str] = None          # ro.build.version.incremental
+    model: Optional[str] = None
+    name: Optional[str] = None        # marketing name, if any
+
+
+def adb_path() -> Optional[str]:
+    """Locate an adb binary, or None if unavailable."""
+    env = os.environ.get("TCL_FW_ADB")
+    if env and Path(env).exists():
+        return env
+    bundled = Path(__file__).resolve().parent.parent / "platform-tools" / (
+        "adb.exe" if os.name == "nt" else "adb"
+    )
+    if bundled.exists():
+        return str(bundled)
+    return shutil.which("adb")
+
+
+def _adb(args: list[str], serial: Optional[str] = None, timeout: int = 10) -> str:
+    exe = adb_path()
+    if not exe:
+        raise RuntimeError("adb not found (set TCL_FW_ADB, add adb to PATH, "
+                           "or drop platform-tools/ next to tcl-fw)")
+    cmd = [exe]
+    if serial:
+        cmd += ["-s", serial]
+    cmd += args
+    out = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+    if out.returncode != 0:
+        raise RuntimeError((out.stderr or out.stdout or "adb error").strip())
+    return out.stdout.strip()
+
+
+def available() -> bool:
+    return adb_path() is not None
+
+
+def list_serials() -> list[str]:
+    """Authorized, online device serials (skips 'unauthorized' / 'offline')."""
+    try:
+        out = _adb(["devices"])
+    except Exception:
+        return []
+    serials = []
+    for line in out.splitlines()[1:]:
+        parts = line.split()
+        if len(parts) >= 2 and parts[1] == "device":
+            serials.append(parts[0])
+    return serials
+
+
+def _getprop(serial: str, prop: str) -> Optional[str]:
+    try:
+        v = _adb(["shell", "getprop", prop], serial=serial).strip()
+        return v or None
+    except Exception:
+        return None
+
+
+def read_device(serial: str) -> Device:
+    """Read curef / firmware-version / model from one device."""
+    curef = _getprop(serial, "ro.tct.curef") or _getprop(serial, "ro.vendor.tct.curef")
+    fv = _getprop(serial, "ro.build.version.incremental")
+    model = _getprop(serial, "ro.product.model")
+    name = _getprop(serial, "ro.tct.setupwizard.marketname") or model
+    return Device(serial=serial, curef=curef, fv=fv, model=model, name=name)
+
+
+def detect() -> Optional[Device]:
+    """Return the first connected device's identity, or None if nothing usable."""
+    serials = list_serials()
+    if not serials:
+        return None
+    return read_device(serials[0])