linux-image-manager 2.1.0__tar.gz → 2.2.0__tar.gz

{linux_image_manager-2.1.0 → linux_image_manager-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: linux-image-manager
-Version: 2.1.0
+Version: 2.2.0
 Summary: CLI (`lim`) for downloading, verifying and flashing Linux images, LUKS/Btrfs encrypted storage (single drive and RAID1), image backups and chroot maintenance
 Author-email: Kevin Veen-Birkenbach <kevin@veen.world>
 Maintainer-email: Kevin Veen-Birkenbach <kevin@veen.world>
@@ -28,6 +28,7 @@ Linux Image Manager (lim) is a Python tool for downloading, configuring, and man
 
 - **Image Download & Setup:** Automatically download, verify (checksum + GPG signature) and prepare Linux distributions.
 - **Encrypted Storage:** Configure LUKS encryption for secure image management.
+- **Tor Onion Unlock:** Optionally bake a Tor onion service into the initramfs so the dropbear LUKS unlock shell stays reachable behind NAT or dynamic IPs.
 - **Virtual RAID1:** Easily set up virtual Btrfs RAID1 for data redundancy.
 - **Backup & Restore:** Create image backups from devices using dd.
 - **Chroot Environment:** Easily enter a chroot shell to maintain or modify Linux images.
@@ -44,7 +45,7 @@ package-manager install lim
 
 This command makes Linux Image Manager globally available as `lim` in your terminal. The `lim` alias points to the **main.py** entry point.
 
-There are no Python dependencies beyond the standard library. The commands call the usual system tools (`cryptsetup`, `fdisk`, `dd`, `rsync`, `wget`, `gpg`, `encfs`, `pv`, `bsdtar`, ...), so those need to be installed for the command you use.
+The only Python dependency is **PyYAML** (`>=6`), used to read the image catalog. The pip/wheel install pulls it in automatically; on the `package-manager`/symlink install path make sure it is present (`python-yaml` on Arch). The commands also call the usual system tools (`cryptsetup`, `fdisk`, `dd`, `rsync`, `wget`, `gpg`, `encfs`, `pv`, `bsdtar`, ...), so those need to be installed for the command you use.
 
 ## Usage ⚙️
 
@@ -112,6 +113,8 @@ lim/
   distributions.yml   # single point of truth for the image catalog
   configuration/      # package collections used during image setup
 tests/unit/           # unit tests (all external commands mocked)
+tests/e2e/            # Tor onion unlock end-to-end tests (rootless + QEMU, opt-in)
+tests/e2e/qemu/       # full virtualized build+boot+unlock harness
 tests/lint/           # architecture guards (e.g. max file length)
 ```
 
@@ -120,15 +123,83 @@ tests/lint/           # architecture guards (e.g. max file length)
 Customize your environment in the `lim/configuration/` folder:
 - **General Packages:** Contains common packages for all setup scripts.
 - **Server LUKS Packages:** Contains packages needed for setting up LUKS encryption on servers.
+- **initcpio Hooks:** The mkinitcpio install/runtime hooks and torrc baked into images for the Tor onion unlock.
+
+## Remote LUKS Unlock via Tor 🧅
+
+When you answer yes to *"Should the system be remotely unlockable via a Tor
+onion service?"* during an encrypted `lim --type image` setup, the image gets:
+
+- `tor` and `busybox` installed, plus a custom `tor` mkinitcpio hook ordered
+  between `netconf` and `dropbear`.
+- A v3 onion service key generated **offline** inside the image chroot; the
+  resulting `.onion` address is printed at the end of the setup and stays
+  stable across reboots and IP changes.
+- An NTP clock sync in early userspace (boards like the Raspberry Pi have no
+  RTC and would otherwise boot with a clock Tor rejects). Override the server
+  with the kernel parameter `tor_ntp=<host>`.
+
+After booting the device, unlock it from any machine with a running Tor
+client:
+
+```bash
+torsocks ssh root@<onion-address>
+```
+
+Typing the LUKS passphrase into that shell resumes the boot. The direct
+`ssh root@<ip>` unlock keeps working as before; Tor is an additional path,
+useful behind NAT/CGNAT where no port forwarding is possible.
+
+**Security note:** the onion private key is stored in the initramfs on the
+unencrypted boot partition. Anyone with physical access to the SD card can
+read it and impersonate the onion service — treat the address as
+non-secret. Access control remains the SSH public key
+(`/etc/dropbear/root_key`), exactly as with the direct unlock.
 
 ## Development & Tests 🧪
 
-The test suite mocks all external commands, so it runs safely on any machine:
+The unit suite mocks all external commands, so it runs safely on any machine:
 
 ```bash
 pytest
 ```
 
+### Tor unlock end-to-end test
+
+`tests/e2e/test_tor_unlock_e2e.py` reproduces the operator-visible half of the
+Tor decryption process **rootless** — no block devices, no `cryptsetup`, no
+`chroot`. It generates the v3 onion keys offline (exactly as `lim.image.tor`
+does inside the image), starts a real Tor onion service from a torrc mirroring
+the baked-in one, then connects to the `.onion` address through Tor and
+delivers a passphrase to a dropbear stand-in, asserting it arrives and the
+endpoint "unlocks".
+
+It needs the real `tor` binary and live Tor network access (onion bootstrap is
+slow), so it is opt-in and skipped otherwise:
+
+```bash
+LIM_E2E_TOR=1 pytest tests/e2e/test_tor_unlock_e2e.py -v
+```
+
+The offline-only checks in that file (onion keygen, production-flag guard) run
+without network. The physical flashing half (`dd`, `cryptsetup luksFormat`,
+`mount`, `chroot`, `mkinitcpio`) requires root and a matching CPU/qemu setup and
+is not covered by this rootless test.
+
+### Full virtualized unlock (QEMU)
+
+For the *whole* process — build an encrypted image, boot it, run the real
+initramfs Tor+dropbear chain, and unlock it — `tests/e2e/qemu/` drives a QEMU
+virtual machine end to end and asserts the real system booted only after the
+passphrase was delivered over Tor. It is opt-in (`LIM_E2E_QEMU=1`) and needs
+QEMU, `arch-install-scripts`, `cryptsetup`, `tor` and `ncat`; the build stage
+needs root (ideally inside a throwaway VM to keep the host rootless). A private,
+offline Tor network via [chutney](https://gitlab.torproject.org/tpo/core/chutney)
+is supported. See [tests/e2e/qemu/README.md](tests/e2e/qemu/README.md).
+
+The harness's pure logic and drift guards run in the normal suite
+(`test_qemu_harness_unit.py`) — no QEMU, root, or network needed.
+
 ## License 📜
 
 This project is licensed under the GNU General Public License Version 3. See the [LICENSE.txt](./LICENSE.txt) file for details.

{linux_image_manager-2.1.0 → linux_image_manager-2.2.0}/README.md

@@ -10,6 +10,7 @@ Linux Image Manager (lim) is a Python tool for downloading, configuring, and man
 
 - **Image Download & Setup:** Automatically download, verify (checksum + GPG signature) and prepare Linux distributions.
 - **Encrypted Storage:** Configure LUKS encryption for secure image management.
+- **Tor Onion Unlock:** Optionally bake a Tor onion service into the initramfs so the dropbear LUKS unlock shell stays reachable behind NAT or dynamic IPs.
 - **Virtual RAID1:** Easily set up virtual Btrfs RAID1 for data redundancy.
 - **Backup & Restore:** Create image backups from devices using dd.
 - **Chroot Environment:** Easily enter a chroot shell to maintain or modify Linux images.
@@ -26,7 +27,7 @@ package-manager install lim
 
 This command makes Linux Image Manager globally available as `lim` in your terminal. The `lim` alias points to the **main.py** entry point.
 
-There are no Python dependencies beyond the standard library. The commands call the usual system tools (`cryptsetup`, `fdisk`, `dd`, `rsync`, `wget`, `gpg`, `encfs`, `pv`, `bsdtar`, ...), so those need to be installed for the command you use.
+The only Python dependency is **PyYAML** (`>=6`), used to read the image catalog. The pip/wheel install pulls it in automatically; on the `package-manager`/symlink install path make sure it is present (`python-yaml` on Arch). The commands also call the usual system tools (`cryptsetup`, `fdisk`, `dd`, `rsync`, `wget`, `gpg`, `encfs`, `pv`, `bsdtar`, ...), so those need to be installed for the command you use.
 
 ## Usage ⚙️
 
@@ -94,6 +95,8 @@ lim/
   distributions.yml   # single point of truth for the image catalog
   configuration/      # package collections used during image setup
 tests/unit/           # unit tests (all external commands mocked)
+tests/e2e/            # Tor onion unlock end-to-end tests (rootless + QEMU, opt-in)
+tests/e2e/qemu/       # full virtualized build+boot+unlock harness
 tests/lint/           # architecture guards (e.g. max file length)
 ```
 
@@ -102,15 +105,83 @@ tests/lint/           # architecture guards (e.g. max file length)
 Customize your environment in the `lim/configuration/` folder:
 - **General Packages:** Contains common packages for all setup scripts.
 - **Server LUKS Packages:** Contains packages needed for setting up LUKS encryption on servers.
+- **initcpio Hooks:** The mkinitcpio install/runtime hooks and torrc baked into images for the Tor onion unlock.
+
+## Remote LUKS Unlock via Tor 🧅
+
+When you answer yes to *"Should the system be remotely unlockable via a Tor
+onion service?"* during an encrypted `lim --type image` setup, the image gets:
+
+- `tor` and `busybox` installed, plus a custom `tor` mkinitcpio hook ordered
+  between `netconf` and `dropbear`.
+- A v3 onion service key generated **offline** inside the image chroot; the
+  resulting `.onion` address is printed at the end of the setup and stays
+  stable across reboots and IP changes.
+- An NTP clock sync in early userspace (boards like the Raspberry Pi have no
+  RTC and would otherwise boot with a clock Tor rejects). Override the server
+  with the kernel parameter `tor_ntp=<host>`.
+
+After booting the device, unlock it from any machine with a running Tor
+client:
+
+```bash
+torsocks ssh root@<onion-address>
+```
+
+Typing the LUKS passphrase into that shell resumes the boot. The direct
+`ssh root@<ip>` unlock keeps working as before; Tor is an additional path,
+useful behind NAT/CGNAT where no port forwarding is possible.
+
+**Security note:** the onion private key is stored in the initramfs on the
+unencrypted boot partition. Anyone with physical access to the SD card can
+read it and impersonate the onion service — treat the address as
+non-secret. Access control remains the SSH public key
+(`/etc/dropbear/root_key`), exactly as with the direct unlock.
 
 ## Development & Tests 🧪
 
-The test suite mocks all external commands, so it runs safely on any machine:
+The unit suite mocks all external commands, so it runs safely on any machine:
 
 ```bash
 pytest
 ```
 
+### Tor unlock end-to-end test
+
+`tests/e2e/test_tor_unlock_e2e.py` reproduces the operator-visible half of the
+Tor decryption process **rootless** — no block devices, no `cryptsetup`, no
+`chroot`. It generates the v3 onion keys offline (exactly as `lim.image.tor`
+does inside the image), starts a real Tor onion service from a torrc mirroring
+the baked-in one, then connects to the `.onion` address through Tor and
+delivers a passphrase to a dropbear stand-in, asserting it arrives and the
+endpoint "unlocks".
+
+It needs the real `tor` binary and live Tor network access (onion bootstrap is
+slow), so it is opt-in and skipped otherwise:
+
+```bash
+LIM_E2E_TOR=1 pytest tests/e2e/test_tor_unlock_e2e.py -v
+```
+
+The offline-only checks in that file (onion keygen, production-flag guard) run
+without network. The physical flashing half (`dd`, `cryptsetup luksFormat`,
+`mount`, `chroot`, `mkinitcpio`) requires root and a matching CPU/qemu setup and
+is not covered by this rootless test.
+
+### Full virtualized unlock (QEMU)
+
+For the *whole* process — build an encrypted image, boot it, run the real
+initramfs Tor+dropbear chain, and unlock it — `tests/e2e/qemu/` drives a QEMU
+virtual machine end to end and asserts the real system booted only after the
+passphrase was delivered over Tor. It is opt-in (`LIM_E2E_QEMU=1`) and needs
+QEMU, `arch-install-scripts`, `cryptsetup`, `tor` and `ncat`; the build stage
+needs root (ideally inside a throwaway VM to keep the host rootless). A private,
+offline Tor network via [chutney](https://gitlab.torproject.org/tpo/core/chutney)
+is supported. See [tests/e2e/qemu/README.md](tests/e2e/qemu/README.md).
+
+The harness's pure logic and drift guards run in the normal suite
+(`test_qemu_harness_unit.py`) — no QEMU, root, or network needed.
+
 ## License 📜
 
 This project is licensed under the GNU General Public License Version 3. See the [LICENSE.txt](./LICENSE.txt) file for details.

linux_image_manager-2.2.0/lim/configuration/initcpio/tor_hook

@@ -0,0 +1,47 @@
+#!/usr/bin/ash
+# mkinitcpio runtime hook: start Tor so the dropbear unlock shell is
+# reachable as an onion service while encryptssh waits for the passphrase.
+# Installed to /etc/initcpio/hooks/tor by linux-image-manager.
+
+# netconf's ipconfig drops its DHCP lease data (incl. DNS) into
+# /tmp/net-*.conf; busybox's resolver only reads /etc/resolv.conf.
+_tor_write_resolv_conf() {
+    [ -s /etc/resolv.conf ] && return 0
+    local conf dns
+    for conf in /tmp/net-*.conf; do
+        [ -f "$conf" ] || continue
+        # Extract ONLY the DNS fields with sed; never source these files —
+        # they hold attacker-controllable DHCP option strings (hostname,
+        # domain, rootpath), and sourcing would run them as root pre-boot.
+        for dns in $(sed -n 's/^IPV4DNS[01]=//p' "$conf"); do
+            [ -n "$dns" ] && [ "$dns" != "0.0.0.0" ] \
+                && echo "nameserver $dns" >> /etc/resolv.conf
+        done
+    done
+    [ -s /etc/resolv.conf ]
+}
+
+run_hook() {
+    # Tor rejects consensus documents when the clock is far off; boards
+    # without an RTC boot in 1970, so sync before starting Tor. Bounded:
+    # a failed sync must never block the boot.
+    msg "tor: syncing clock via NTP..."
+    # Best-effort DNS; a tor_ntp IP literal needs none, so never gate on it.
+    _tor_write_resolv_conf || msg "tor: no DNS from DHCP (fine if tor_ntp is an IP)"
+    /usr/local/bin/busybox timeout 30 \
+        /usr/local/bin/busybox ntpd -n -q -p "${tor_ntp:-pool.ntp.org}" \
+        || msg "tor: NTP sync failed, keeping current clock"
+
+    msg "tor: starting onion service for remote unlock..."
+    mkdir -p /var/lib/tor
+    chmod 0700 /var/lib/tor /etc/tor/onion
+    chmod 0600 /etc/tor/onion/hs_ed25519_secret_key
+    tor -f /etc/tor/torrc --RunAsDaemon 1 --Log "notice file /tmp/tor.log" \
+        || msg "tor: failed to start, unlock stays reachable via direct IP"
+}
+
+run_cleanuphook() {
+    # Nothing from the initramfs may keep running after the pivot.
+    /usr/local/bin/busybox killall tor 2>/dev/null
+    return 0
+}

linux_image_manager-2.2.0/lim/configuration/initcpio/tor_install

@@ -0,0 +1,37 @@
+#!/bin/bash
+# mkinitcpio install hook: Tor onion service for remote LUKS unlock.
+# Installed to /etc/initcpio/install/tor by linux-image-manager.
+
+build() {
+    add_binary /usr/bin/tor
+    # Full busybox for the ntpd applet: boards without an RTC (e.g. most
+    # Raspberry Pis) wake up in 1970, which Tor's consensus checks reject.
+    # A different target path keeps mkinitcpio's own busybox untouched.
+    add_binary /usr/bin/busybox /usr/local/bin/busybox
+    # glibc resolves the NTP server hostname via getaddrinfo(), which dlopen()s
+    # these NSS modules at runtime — add_binary only follows NEEDED libs, so
+    # without them DNS silently fails, ntpd never syncs, and the clock stays
+    # at 1970. glibc's built-in default (no nsswitch.conf) is "dns ... files".
+    add_binary /usr/lib/libnss_dns.so.2
+    add_binary /usr/lib/libnss_files.so.2
+    add_file /etc/tor/initramfs-torrc /etc/tor/torrc
+    add_file /etc/tor/initramfs-onion/hostname /etc/tor/onion/hostname
+    add_file /etc/tor/initramfs-onion/hs_ed25519_public_key /etc/tor/onion/hs_ed25519_public_key
+    add_file /etc/tor/initramfs-onion/hs_ed25519_secret_key /etc/tor/onion/hs_ed25519_secret_key
+    add_runscript
+}
+
+help() {
+    cat <<HELPEOF
+Starts a Tor onion service in early userspace so the dropbear unlock
+shell stays reachable under the .onion address baked into the image,
+even behind NAT or a dynamic IP.
+
+Place it between netconf and dropbear:
+  HOOKS=(... netconf tor dropbear encryptssh ...)
+
+Optional kernel parameter:
+  tor_ntp=<server>  NTP server used to set the clock before Tor starts
+                    (default: pool.ntp.org)
+HELPEOF
+}

linux_image_manager-2.2.0/lim/configuration/initcpio/torrc

@@ -0,0 +1,7 @@
+# Tor configuration for the initramfs onion unlock service.
+# Baked into the initramfs as /etc/tor/torrc by the "tor" mkinitcpio hook;
+# the onion keys come from /etc/tor/initramfs-onion on the system.
+DataDirectory /var/lib/tor
+HiddenServiceDir /etc/tor/onion
+HiddenServicePort 22 127.0.0.1:22
+SocksPort 0

linux_image_manager-2.2.0/lim/configuration/packages/server/tor.txt

@@ -0,0 +1,3 @@
+# Packages for the Tor onion unlock service in the initramfs
+tor
+busybox  # full applet set: ntpd for clock sync on RTC-less boards

{linux_image_manager-2.1.0 → linux_image_manager-2.2.0}/lim/image/encryption.py

@@ -9,6 +9,7 @@ from pathlib import Path
 from lim import catalog, fsutil, packages, runner, ui
 from lim.image.plan import ImagePlan
 from lim.image.session import ImageSession, chroot_bash, install_packages
+from lim.image.tor import configure_tor_unlock
 
 MKINITCPIO_HOOKS_PREFIX = (
     "base udev autodetect microcode modconf kms keyboard keymap consolefont block"
@@ -32,9 +33,10 @@ def _configure_mkinitcpio(plan: ImagePlan, root: Path) -> None:
     fsutil.replace_in_file(
         "BINARIES=()", "BINARIES=(/usr/lib/libgcc_s.so.1)", mkinitcpio_path
     )
+    tor_hook = "tor " if plan.tor_unlock else ""
     fsutil.replace_in_file(
         f"HOOKS=({MKINITCPIO_HOOKS_PREFIX} {MKINITCPIO_HOOKS_SUFFIX})",
-        f"HOOKS=({MKINITCPIO_HOOKS_PREFIX} sleep netconf dropbear encryptssh "
+        f"HOOKS=({MKINITCPIO_HOOKS_PREFIX} sleep netconf {tor_hook}dropbear encryptssh "
         f"{MKINITCPIO_HOOKS_SUFFIX})",
         mkinitcpio_path,
     )
@@ -90,9 +92,15 @@ def _configure_bootloader(plan: ImagePlan, session: ImageSession, root: Path) ->
     else:
         cmdline_txt_path = session.boot_mount_path / "cmdline.txt"
         ui.info(f"Configuring {cmdline_txt_path}...")
+        # Firmware-boot boards (e.g. RPi4 cmdline.txt) need the same early
+        # networking as the boot.txt branch, or the initramfs netconf hook
+        # brings up no interface and remote unlock (dropbear + tor) is
+        # unreachable — the onion never even publishes.
+        hostname = (root / "etc/hostname").read_text().strip()
         fsutil.replace_in_file(
             "root=/dev/mmcblk0p2",
-            f"{cryptdevice} rootfstype={plan.root_filesystem}",
+            f"{cryptdevice} rootfstype={plan.root_filesystem} "
+            f"ip=::::{hostname}:eth0:dhcp net.ifnames=0 biosdevname=0",
             cmdline_txt_path,
         )
         ui.info(f"Content of {cmdline_txt_path}:{cmdline_txt_path.read_text()}")
@@ -112,6 +120,10 @@ def configure_encryption(
     ui.info(f"Adding {authorized_keys} to dropbear...")
     runner.run(["cp", "-v", str(authorized_keys), str(dropbear_root_key_path)], sudo=True)
 
+    if plan.tor_unlock:
+        # Hook files and onion keys must exist before mkinitcpio bakes the image.
+        configure_tor_unlock(plan, root)
+
     _configure_mkinitcpio(plan, root)
     _register_encrypted_root(plan, session, root)
     _configure_bootloader(plan, session, root)

{linux_image_manager-2.1.0 → linux_image_manager-2.2.0}/lim/image/plan.py

@@ -17,6 +17,7 @@ class ImagePlan:
     luks_memory_cost: str | None = None
     raspberry_pi_version: str | None = None
     encrypt_system: bool = False
+    tor_unlock: bool = False
     root_filesystem: str = ""
     image_folder: Path = field(default_factory=Path)
 

{linux_image_manager-2.1.0 → linux_image_manager-2.2.0}/lim/image/setup.py

@@ -49,6 +49,10 @@ def _choose_and_verify_image(plan: ImagePlan) -> None:
     if plan.operation_system == "linux":
         choosers.choose_linux_image(plan)
         plan.encrypt_system = ui.confirm("Should the system be encrypted?")
+        if plan.encrypt_system:
+            plan.tor_unlock = ui.confirm(
+                "Should the system be remotely unlockable via a Tor onion service?"
+            )
         ui.info("Generating os-image...")
         transfer.download_image(plan)
     else:

linux_image_manager-2.2.0/lim/image/tor.py

@@ -0,0 +1,79 @@
+"""Tor onion service in the initramfs for remote LUKS unlock.
+
+The onion keys are generated offline inside the image chroot
+(``tor --DisableNetwork 1`` writes them without touching the network)
+and baked into the initramfs by the "tor" mkinitcpio hook, so the
+dropbear unlock shell stays reachable under a stable .onion address
+even behind NAT or a dynamic IP.
+"""
+
+from pathlib import Path
+
+from lim import config, packages, runner, ui
+from lim.errors import LimError
+from lim.image.plan import ImagePlan
+from lim.image.session import chroot_bash, install_packages
+
+# Paths inside the image (relative to the mounted root).
+ONION_DIR = "etc/tor/initramfs-onion"
+TORRC_PATH = "etc/tor/initramfs-torrc"
+
+# An empty -f torrc keeps the image's /etc/tor/torrc (User tor, ...) out of
+# the keygen run; with DisableNetwork the keys appear within a second, the
+# loop only cushions slow qemu-emulated chroots.
+_KEYGEN_SCRIPT = f"""
+mkdir -p /{ONION_DIR}
+chmod 0700 /{ONION_DIR}
+: > /tmp/tor-keygen-torrc
+tor -f /tmp/tor-keygen-torrc --DisableNetwork 1 \\
+    --DataDirectory /tmp/tor-keygen-data \\
+    --HiddenServiceDir /{ONION_DIR} \\
+    --HiddenServicePort "22 127.0.0.1:22" \\
+    --SocksPort 0 --RunAsDaemon 0 --Log "notice stderr" &
+tor_pid=$!
+for _ in $(seq 1 30); do
+    [ -s /{ONION_DIR}/hostname ] && break
+    sleep 1
+done
+kill "$tor_pid" 2>/dev/null || true
+rm -rf /tmp/tor-keygen-data /tmp/tor-keygen-torrc
+[ -s /{ONION_DIR}/hostname ]
+"""
+
+
+def _install_initcpio_files(root: Path) -> None:
+    source_dir = config.CONFIGURATION_PATH / "initcpio"
+    for source, target in (
+        (source_dir / "tor_install", root / "etc/initcpio/install/tor"),
+        (source_dir / "tor_hook", root / "etc/initcpio/hooks/tor"),
+        (source_dir / "torrc", root / TORRC_PATH),
+    ):
+        ui.info(f"Installing {target}...")
+        runner.run(
+            ["install", "-D", "-m", "0644", str(source), str(target)], sudo=True
+        )
+
+
+def _generate_onion_keys(root: Path) -> str:
+    hostname_path = root / ONION_DIR / "hostname"
+    if hostname_path.is_file():
+        ui.info("Onion keys already exist, keeping the existing address.")
+    else:
+        ui.info("Generating onion service keys (offline, inside the chroot)...")
+        chroot_bash(root, _KEYGEN_SCRIPT, error_msg="Onion key generation failed.")
+        if not hostname_path.is_file():
+            raise LimError(f"Onion key generation produced no {hostname_path}.")
+    return hostname_path.read_text().strip()
+
+
+def configure_tor_unlock(plan: ImagePlan, root: Path) -> str:
+    """Install everything the "tor" mkinitcpio hook bakes in; return the onion address."""
+    ui.info("Setting up remote unlock via Tor onion service...")
+    install_packages(
+        plan.distribution, root, " ".join(packages.get_packages("server/tor"))
+    )
+    _install_initcpio_files(root)
+    onion_address = _generate_onion_keys(root)
+    ui.success(f"Onion unlock address: {onion_address}")
+    ui.info(f"Unlock later with: torsocks ssh root@{onion_address}")
+    return onion_address

{linux_image_manager-2.1.0 → linux_image_manager-2.2.0}/linux_image_manager.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: linux-image-manager
-Version: 2.1.0
+Version: 2.2.0
 Summary: CLI (`lim`) for downloading, verifying and flashing Linux images, LUKS/Btrfs encrypted storage (single drive and RAID1), image backups and chroot maintenance
 Author-email: Kevin Veen-Birkenbach <kevin@veen.world>
 Maintainer-email: Kevin Veen-Birkenbach <kevin@veen.world>
@@ -28,6 +28,7 @@ Linux Image Manager (lim) is a Python tool for downloading, configuring, and man
 
 - **Image Download & Setup:** Automatically download, verify (checksum + GPG signature) and prepare Linux distributions.
 - **Encrypted Storage:** Configure LUKS encryption for secure image management.
+- **Tor Onion Unlock:** Optionally bake a Tor onion service into the initramfs so the dropbear LUKS unlock shell stays reachable behind NAT or dynamic IPs.
 - **Virtual RAID1:** Easily set up virtual Btrfs RAID1 for data redundancy.
 - **Backup & Restore:** Create image backups from devices using dd.
 - **Chroot Environment:** Easily enter a chroot shell to maintain or modify Linux images.
@@ -44,7 +45,7 @@ package-manager install lim
 
 This command makes Linux Image Manager globally available as `lim` in your terminal. The `lim` alias points to the **main.py** entry point.
 
-There are no Python dependencies beyond the standard library. The commands call the usual system tools (`cryptsetup`, `fdisk`, `dd`, `rsync`, `wget`, `gpg`, `encfs`, `pv`, `bsdtar`, ...), so those need to be installed for the command you use.
+The only Python dependency is **PyYAML** (`>=6`), used to read the image catalog. The pip/wheel install pulls it in automatically; on the `package-manager`/symlink install path make sure it is present (`python-yaml` on Arch). The commands also call the usual system tools (`cryptsetup`, `fdisk`, `dd`, `rsync`, `wget`, `gpg`, `encfs`, `pv`, `bsdtar`, ...), so those need to be installed for the command you use.
 
 ## Usage ⚙️
 
@@ -112,6 +113,8 @@ lim/
   distributions.yml   # single point of truth for the image catalog
   configuration/      # package collections used during image setup
 tests/unit/           # unit tests (all external commands mocked)
+tests/e2e/            # Tor onion unlock end-to-end tests (rootless + QEMU, opt-in)
+tests/e2e/qemu/       # full virtualized build+boot+unlock harness
 tests/lint/           # architecture guards (e.g. max file length)
 ```
 
@@ -120,15 +123,83 @@ tests/lint/           # architecture guards (e.g. max file length)
 Customize your environment in the `lim/configuration/` folder:
 - **General Packages:** Contains common packages for all setup scripts.
 - **Server LUKS Packages:** Contains packages needed for setting up LUKS encryption on servers.
+- **initcpio Hooks:** The mkinitcpio install/runtime hooks and torrc baked into images for the Tor onion unlock.
+
+## Remote LUKS Unlock via Tor 🧅
+
+When you answer yes to *"Should the system be remotely unlockable via a Tor
+onion service?"* during an encrypted `lim --type image` setup, the image gets:
+
+- `tor` and `busybox` installed, plus a custom `tor` mkinitcpio hook ordered
+  between `netconf` and `dropbear`.
+- A v3 onion service key generated **offline** inside the image chroot; the
+  resulting `.onion` address is printed at the end of the setup and stays
+  stable across reboots and IP changes.
+- An NTP clock sync in early userspace (boards like the Raspberry Pi have no
+  RTC and would otherwise boot with a clock Tor rejects). Override the server
+  with the kernel parameter `tor_ntp=<host>`.
+
+After booting the device, unlock it from any machine with a running Tor
+client:
+
+```bash
+torsocks ssh root@<onion-address>
+```
+
+Typing the LUKS passphrase into that shell resumes the boot. The direct
+`ssh root@<ip>` unlock keeps working as before; Tor is an additional path,
+useful behind NAT/CGNAT where no port forwarding is possible.
+
+**Security note:** the onion private key is stored in the initramfs on the
+unencrypted boot partition. Anyone with physical access to the SD card can
+read it and impersonate the onion service — treat the address as
+non-secret. Access control remains the SSH public key
+(`/etc/dropbear/root_key`), exactly as with the direct unlock.
 
 ## Development & Tests 🧪
 
-The test suite mocks all external commands, so it runs safely on any machine:
+The unit suite mocks all external commands, so it runs safely on any machine:
 
 ```bash
 pytest
 ```
 
+### Tor unlock end-to-end test
+
+`tests/e2e/test_tor_unlock_e2e.py` reproduces the operator-visible half of the
+Tor decryption process **rootless** — no block devices, no `cryptsetup`, no
+`chroot`. It generates the v3 onion keys offline (exactly as `lim.image.tor`
+does inside the image), starts a real Tor onion service from a torrc mirroring
+the baked-in one, then connects to the `.onion` address through Tor and
+delivers a passphrase to a dropbear stand-in, asserting it arrives and the
+endpoint "unlocks".
+
+It needs the real `tor` binary and live Tor network access (onion bootstrap is
+slow), so it is opt-in and skipped otherwise:
+
+```bash
+LIM_E2E_TOR=1 pytest tests/e2e/test_tor_unlock_e2e.py -v
+```
+
+The offline-only checks in that file (onion keygen, production-flag guard) run
+without network. The physical flashing half (`dd`, `cryptsetup luksFormat`,
+`mount`, `chroot`, `mkinitcpio`) requires root and a matching CPU/qemu setup and
+is not covered by this rootless test.
+
+### Full virtualized unlock (QEMU)
+
+For the *whole* process — build an encrypted image, boot it, run the real
+initramfs Tor+dropbear chain, and unlock it — `tests/e2e/qemu/` drives a QEMU
+virtual machine end to end and asserts the real system booted only after the
+passphrase was delivered over Tor. It is opt-in (`LIM_E2E_QEMU=1`) and needs
+QEMU, `arch-install-scripts`, `cryptsetup`, `tor` and `ncat`; the build stage
+needs root (ideally inside a throwaway VM to keep the host rootless). A private,
+offline Tor network via [chutney](https://gitlab.torproject.org/tpo/core/chutney)
+is supported. See [tests/e2e/qemu/README.md](tests/e2e/qemu/README.md).
+
+The harness's pure logic and drift guards run in the normal suite
+(`test_qemu_harness_unit.py`) — no QEMU, root, or network needed.
+
 ## License 📜
 
 This project is licensed under the GNU General Public License Version 3. See the [LICENSE.txt](./LICENSE.txt) file for details.

{linux_image_manager-2.1.0 → linux_image_manager-2.2.0}/linux_image_manager.egg-info/SOURCES.txt

@@ -14,8 +14,12 @@ lim/packages.py
 lim/runner.py
 lim/system.py
 lim/ui.py
+lim/configuration/initcpio/tor_hook
+lim/configuration/initcpio/tor_install
+lim/configuration/initcpio/torrc
 lim/configuration/packages/general.txt
 lim/configuration/packages/server/luks.txt
+lim/configuration/packages/server/tor.txt
 lim/data/__init__.py
 lim/data/crypt.py
 lim/data/sync.py
@@ -28,6 +32,7 @@ lim/image/plan.py
 lim/image/raspberry.py
 lim/image/session.py
 lim/image/setup.py
+lim/image/tor.py
 lim/image/transfer.py
 lim/image/verify.py
 lim/storage/__init__.py

{linux_image_manager-2.1.0 → linux_image_manager-2.2.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "linux-image-manager"
-version = "2.1.0"
+version = "2.2.0"
 description = "CLI (`lim`) for downloading, verifying and flashing Linux images, LUKS/Btrfs encrypted storage (single drive and RAID1), image backups and chroot maintenance"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -28,7 +28,11 @@ lim = "lim.cli:main"
 include = ["lim*"]
 
 [tool.setuptools.package-data]
-lim = ["distributions.yml", "configuration/packages/**/*.txt"]
+lim = [
+  "distributions.yml",
+  "configuration/packages/**/*.txt",
+  "configuration/initcpio/*",
+]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]