audit: fix sysdata path, verify layer digests, drop legacy alias

Three issues surfaced while auditing the new container layout:

  1. setup_fake_sysdata() and fake_proc_bindings() still wrote to and
     bound from installed-rootfs/<name>/. login binds rootfs/sys/.empty
     from the new path, so the empty file was missing inside the
     container. Both helpers now take the rootfs path directly and
     keep stub files co-located with the container.

  2. _download_blob() did not verify layer integrity, contrary to the
     architecture spec. It now streams each blob through hashlib.sha256
     and rejects mismatched digests before promoting the temp file
     into the cache. Only sha256 is accepted.

  3. INSTALLED_ROOTFS_DIR was kept as a back-compat alias of the legacy
     path. Its only remaining users (arch.py fallback, sysdata.py)
     have moved to CONTAINERS_DIR, so the alias and the unused private
     name re-exports in helpers/rootfs.py are removed.

CLAUDE.md updated to describe the new sysdata layout and the layer
integrity check, and to reflect detect_installed_arch() resolving
bare names against CONTAINERS_DIR.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: sylirre

CLAUDE.md

@@ -203,7 +203,8 @@ attributes.
 - Installed arch detected by `detect_installed_arch(rootfs_path)` in
   `arch.py`: reads the first 20 bytes of candidate ELF binaries, checks
   magic, reads endianness from `EI_DATA`, unpacks `e_machine` with `struct`,
-  and maps via `_ELF_MACHINE_MAP`. Accepts a full rootfs path or dist name.
+  and maps via `_ELF_MACHINE_MAP`. Accepts either a full rootfs path or a
+  bare container name (resolved as `CONTAINERS_DIR/<name>/rootfs`).
 - 32-bit support on AArch64 probed via `ctypes.CDLL(None).personality(PER_LINUX32)`
 - Cross-arch: proot `-q qemu-*` (QEMU user-mode)
 - 32-bit guests on 64-bit hosts run natively when supported
@@ -232,6 +233,16 @@ URLs. CDN hosts reject `Bearer` tokens (HTTP 400).
 `_AuthStrippingRedirectHandler` strips the `Authorization` header on
 cross-host redirects.
 
+**Layer integrity:** `_download_blob()` streams the blob through a
+`hashlib.sha256` hasher while writing it. After the body is fully read the
+computed digest is compared to the expected one from the manifest; on
+mismatch the temp file is unlinked and `RuntimeError` is raised before any
+data is promoted into the cache. Only `sha256` digests are accepted (the
+only algorithm currently used by Docker Hub and the OCI distribution
+spec). Cached layers are trusted because the cache only ever contains
+verified blobs — verification happens before `os.replace` moves the temp
+file to its final location.
+
 **`parse_image_ref(image_ref)`** returns `(registry, repo, tag)` where
 `registry` is empty for Docker Hub images.
 
@@ -330,9 +341,20 @@ Uses `os.scandir` for iteration, `shutil.rmtree` for subdirectories,
 
 ### Fake sysdata
 
-On login, fake `/proc` and `/sys` entries are written to `$PREFIX/var/lib/proot-distro/`
-and bind-mounted read-only. Constants `_FAKE_LOADAVG`, `_FAKE_STAT`,
-`_FAKE_UPTIME`, `_FAKE_VMSTAT` are hardcoded in `proot_distro/sysdata.py`.
+On install and on every login of a `normal`-type container, fake `/proc`
+and `/sys` stub files are written **inside the container's own rootfs**
+(`containers/<name>/rootfs/proc/.loadavg`, `…/.stat`, `…/.uptime`,
+`…/.version`, `…/.vmstat`, `…/.sysctl_entry_cap_last_cap`,
+`…/.sysctl_inotify_max_user_watches`, plus `…/sys/.empty`) and then
+bind-mounted by proot over the corresponding `/proc/*` and
+`/sys/fs/selinux` paths. Storing them inside the rootfs keeps them
+co-located with the container, so `remove` cleans them up automatically.
+Both `setup_fake_sysdata(rootfs)` and `fake_proc_bindings(rootfs)` take
+the absolute rootfs path as their argument. Constants `_FAKE_LOADAVG`,
+`_FAKE_STAT`, `_FAKE_UPTIME`, `_FAKE_VMSTAT` are hardcoded in
+`proot_distro/sysdata.py`. `termux`-type containers do not get fake
+sysdata (they share the host's `/proc` and `/sys` via the existing
+`--bind=/proc` / `--bind=/sys`).
 
 ### Subcommand help
 

proot_distro/arch.py

@@ -29,7 +29,7 @@
 import struct
 import sys
 
-from proot_distro.constants import PREFIX, INSTALLED_ROOTFS_DIR
+from proot_distro.constants import PREFIX, CONTAINERS_DIR
 from proot_distro.colors import C, msg
 
 
@@ -89,15 +89,15 @@ def _elf_arch(path: str) -> str:
 
 
 def detect_installed_arch(dist_name_or_rootfs: str) -> str:
-    """Detect CPU architecture of an installed distro by reading ELF headers.
+    """Detect CPU architecture of an installed container by reading ELF headers.
 
-    Accepts either a plain distribution name (looked up under INSTALLED_ROOTFS_DIR)
-    or a full path to the rootfs directory.
+    Accepts either a plain container name (resolved as
+    ``CONTAINERS_DIR/<name>/rootfs``) or a full path to the rootfs directory.
     """
     if os.sep in dist_name_or_rootfs or dist_name_or_rootfs.startswith("/"):
         root = dist_name_or_rootfs
     else:
-        root = os.path.join(INSTALLED_ROOTFS_DIR, dist_name_or_rootfs)
+        root = os.path.join(CONTAINERS_DIR, dist_name_or_rootfs, "rootfs")
 
     candidates = [
         "/usr/bin/bash", "/usr/bin/sh", "/usr/bin/su", "/usr/bin/busybox",

proot_distro/commands/install.py

@@ -156,7 +156,7 @@ def _cleanup() -> None:
             f"Registering Android-specific UIDs and GIDs...{C['RST']}")
         register_android_ids(rootfs_dir)
 
-        setup_fake_sysdata(install_name)
+        setup_fake_sysdata(rootfs_dir)
 
         image_env = metadata.get("env", [])
         if image_env:

proot_distro/commands/login.py

@@ -365,7 +365,7 @@ def command_login(args, configs: dict) -> None:  # noqa: ARG001
             + shell_args
         )
 
-        setup_fake_sysdata(dist_name)
+        setup_fake_sysdata(rootfs)
 
     # Architecture detection.
     target_arch = detect_installed_arch(rootfs)
@@ -425,7 +425,7 @@ def command_login(args, configs: dict) -> None:  # noqa: ARG001
                 proot_args.append(f"--bind=/proc/self/fd/{i}:/dev/{name}")
 
         proot_args.append(f"--bind={rootfs}/sys/.empty:/sys/fs/selinux")
-        proot_args += fake_proc_bindings(dist_name)
+        proot_args += fake_proc_bindings(rootfs)
 
         tmp_dir = os.path.join(rootfs, "tmp")
         os.makedirs(tmp_dir, exist_ok=True)

proot_distro/constants.py

@@ -57,9 +57,6 @@
 # Legacy rootfs path — used only for migrating old installations.
 LEGACY_ROOTFS_DIR = os.path.join(RUNTIME_DIR, "installed-rootfs")
 
-# Kept for backward compatibility during transition; points to legacy path.
-INSTALLED_ROOTFS_DIR = LEGACY_ROOTFS_DIR
-
 # Layer and manifest caches (subdirectories of the download cache).
 LAYER_CACHE_DIR = os.path.join(DOWNLOAD_CACHE_DIR, "layers")
 MANIFEST_CACHE_DIR = os.path.join(DOWNLOAD_CACHE_DIR, "manifests")

proot_distro/helpers/docker.py

@@ -25,6 +25,7 @@
 # tokens are stripped on cross-host redirects because CDN pre-signed URLs
 # reject them with HTTP 400.
 
+import hashlib
 import json
 import os
 import re
@@ -322,7 +323,12 @@ def _fetch_config_blob(
 def _download_blob(
     repo: str, digest: str, token: str, registry: str = ""
 ) -> str:
-    """Download a blob to the layer cache; return the local file path."""
+    """Download a blob to the layer cache; return the local file path.
+
+    Computes the SHA-256 of the blob while it streams to disk and verifies
+    it against the expected *digest* before promoting the temp file to its
+    final location. The cache therefore only ever contains intact layers.
+    """
     dest = _layer_cache_path(digest)
     os.makedirs(os.path.dirname(dest), exist_ok=True)
     if os.path.isfile(dest):
@@ -336,6 +342,17 @@ def _download_blob(
     req = urllib.request.Request(url, headers=headers)
     tmp = dest + ".tmp"
     use_tty = sys.stderr.isatty()
+
+    if ":" not in digest:
+        raise RuntimeError(f"Malformed layer digest '{digest}'.")
+    algo, expected_hex = digest.split(":", 1)
+    if algo.lower() != "sha256":
+        raise RuntimeError(
+            f"Unsupported layer digest algorithm '{algo}' (only sha256 "
+            f"is supported)."
+        )
+    hasher = hashlib.sha256()
+
     try:
         with _auth_stripping_opener.open(req) as resp, open(tmp, "wb") as fh:
             total = int(resp.headers.get("Content-Length", 0))
@@ -345,6 +362,7 @@ def _download_blob(
                 if not chunk:
                     break
                 fh.write(chunk)
+                hasher.update(chunk)
                 downloaded += len(chunk)
                 if use_tty:
                     pfx = f"{C['BLUE']}[{C['GREEN']}*{C['BLUE']}] {C['CYAN']}"
@@ -363,6 +381,14 @@ def _download_blob(
         if use_tty:
             sys.stderr.write("\r\033[K")
             sys.stderr.flush()
+
+        actual_hex = hasher.hexdigest()
+        if actual_hex != expected_hex.lower():
+            raise RuntimeError(
+                f"Layer integrity check failed for digest '{digest}': "
+                f"expected {expected_hex}, got {actual_hex}."
+            )
+
         os.replace(tmp, dest)
     except BaseException:
         if use_tty:

proot_distro/helpers/rootfs.py

@@ -193,14 +193,3 @@ def register_android_ids(rootfs: str) -> None:
                     )
         except OSError:
             pass
-
-
-# ---------------------------------------------------------------------------
-# Backward-compatible aliases (kept for callers still using old names)
-# ---------------------------------------------------------------------------
-
-_write_environment = write_environment
-_fix_path_in_configs = fix_path_in_configs
-_write_resolv_conf = write_resolv_conf
-_write_hosts = write_hosts
-_register_android_ids = register_android_ids

proot_distro/sysdata.py

@@ -21,13 +21,14 @@
 # Architecture: Supplies fake /proc and /sys content that proot bind-mounts
 # read-only into the container. Android restricts or blocks several /proc
 # files; providing static replacements ensures distro tools that read them
-# (top, htop, etc.) work correctly. setup_fake_sysdata() takes a dist_name
-# and resolves the path internally for backward compatibility.
+# (top, htop, etc.) work correctly. The fake files live inside the
+# container's own rootfs (containers/<name>/rootfs/proc/.* and sys/.empty)
+# so they are removed together with the container and stay aligned with the
+# new storage layout.
 
 import os
 
 from proot_distro.constants import (
-    INSTALLED_ROOTFS_DIR,
     DEFAULT_FAKE_KERNEL_RELEASE,
     DEFAULT_FAKE_KERNEL_VERSION,
 )
@@ -243,11 +244,14 @@ def _write_if_missing(path: str, content: str) -> None:
             fh.write(content)
 
 
-def setup_fake_sysdata(dist_name: str) -> None:
-    """Create fake /proc and /sys stubs required by proot on Android."""
-    root = os.path.join(INSTALLED_ROOTFS_DIR, dist_name)
+def setup_fake_sysdata(rootfs: str) -> None:
+    """Create fake /proc and /sys stubs required by proot on Android.
+
+    *rootfs* is the absolute path to the container's rootfs directory
+    (e.g. ``$RUNTIME_DIR/containers/<name>/rootfs``).
+    """
     for d in ("proc", "sys", "sys/.empty"):
-        p = os.path.join(root, d)
+        p = os.path.join(rootfs, d)
         os.makedirs(p, exist_ok=True)
         os.chmod(p, 0o700)
 
@@ -257,22 +261,25 @@ def setup_fake_sysdata(dist_name: str) -> None:
         f"{DEFAULT_FAKE_KERNEL_VERSION}\n"
     )
 
-    _write_if_missing(os.path.join(root, "proc/.loadavg"), _FAKE_LOADAVG)
-    _write_if_missing(os.path.join(root, "proc/.stat"), _FAKE_STAT)
-    _write_if_missing(os.path.join(root, "proc/.uptime"), _FAKE_UPTIME)
-    _write_if_missing(os.path.join(root, "proc/.version"), fake_version)
-    _write_if_missing(os.path.join(root, "proc/.vmstat"), _FAKE_VMSTAT)
+    _write_if_missing(os.path.join(rootfs, "proc/.loadavg"), _FAKE_LOADAVG)
+    _write_if_missing(os.path.join(rootfs, "proc/.stat"), _FAKE_STAT)
+    _write_if_missing(os.path.join(rootfs, "proc/.uptime"), _FAKE_UPTIME)
+    _write_if_missing(os.path.join(rootfs, "proc/.version"), fake_version)
+    _write_if_missing(os.path.join(rootfs, "proc/.vmstat"), _FAKE_VMSTAT)
     _write_if_missing(
-        os.path.join(root, "proc/.sysctl_entry_cap_last_cap"), "40\n"
+        os.path.join(rootfs, "proc/.sysctl_entry_cap_last_cap"), "40\n"
     )
     _write_if_missing(
-        os.path.join(root, "proc/.sysctl_inotify_max_user_watches"), "4096\n"
+        os.path.join(rootfs, "proc/.sysctl_inotify_max_user_watches"),
+        "4096\n",
     )
 
 
-def fake_proc_bindings(dist_name: str) -> list:
-    """Return --bind args for fake /proc entries that are unreadable on Android."""
-    root = os.path.join(INSTALLED_ROOTFS_DIR, dist_name)
+def fake_proc_bindings(rootfs: str) -> list:
+    """Return --bind args for fake /proc entries unreadable on Android.
+
+    *rootfs* is the absolute path to the container's rootfs directory.
+    """
     bindings = []
     checks = [
         ("/proc/loadavg",                        "proc/.loadavg"),
@@ -289,6 +296,6 @@ def fake_proc_bindings(dist_name: str) -> list:
                 fh.read(1)
         except OSError:
             bindings.append(
-                f"--bind={os.path.join(root, fake_rel)}:{real}"
+                f"--bind={os.path.join(rootfs, fake_rel)}:{real}"
             )
     return bindings