feat(ngclient): require explicit bootstrap argument

make bootstrap required and explicit: callers must pass bootstrap=<root_bytes> or bootstrap=None.

also tighten docs, examples, and tests to reflect the explicit trust anchor choice.

Signed-off-by: 1seal <security@1seal.org>

Author: 1seal

docs/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+### Changed
+
+* ngclient: `Updater()` now requires an explicit `bootstrap` argument
+  * This is a breaking change: callers must pass `bootstrap=<root_bytes>` or `bootstrap=None`
+  * `bootstrap=None` explicitly opts into using cached `root.json` as trust anchor
+
 ## v6.0.0
 
 This release is not strictly speaking an API break from 5.1 but it does contain some

docs/INSTALLATION.rst

@@ -53,6 +53,39 @@ from GitHub, change into the project root directory, and install with pip
    python3 -m pip install -r requirements/dev.txt
 
 
+Bootstrap root metadata
+-----------------------
+
+The initial trusted root metadata (``root.json``) is the trust anchor for all
+subsequent metadata verification. Applications should deploy a trusted root
+with the application and provide it to :class:`tuf.ngclient.Updater`.
+
+Recommended storage locations for bootstrap root metadata include:
+
+* a system-wide read-only path (e.g. ``/usr/share/your-app/root.json``)
+* an application bundle with appropriate permissions
+* a read-only mounted volume in containerized deployments
+
+Not recommended:
+
+* ``metadata_dir`` (the metadata cache) since it is writable by design
+* user-writable install paths (e.g. a user site-packages directory)
+* any location writable by the account running the updater
+
+Example::
+
+   from tuf.ngclient import Updater
+
+   with open("/usr/share/your-app/root.json", "rb") as f:
+       bootstrap = f.read()
+
+   updater = Updater(
+       metadata_dir="/var/lib/your-app/tuf/metadata",
+       metadata_base_url="https://example.com/metadata/",
+       bootstrap=bootstrap,
+   )
+
+
 Verify release signatures
 -------------------------
 

examples/client/client

@@ -79,14 +79,15 @@ def download(base_url: str, target: str) -> bool:
     print(f"Using trusted root in {metadata_dir}")
 
     try:
-        # NOTE: initial root should be provided with ``bootstrap``  argument:
-        # This examples uses unsafe Trust-On-First-Use initialization so it is
-        # not possible here.
+        # NOTE: production deployments should provide embedded root metadata
+        # bytes via the ``bootstrap`` argument. This example uses Trust-On-First-Use
+        # initialization, so it explicitly opts into using cached root.json.
         updater = Updater(
             metadata_dir=metadata_dir,
             metadata_base_url=f"{base_url}/metadata/",
             target_base_url=f"{base_url}/targets/",
             target_dir=DOWNLOAD_DIR,
+            bootstrap=None,
         )
         updater.refresh()
 

examples/uploader/_localrepo.py

@@ -47,6 +47,7 @@ def __init__(self, metadata_dir: str, key_dir: str, base_url: str):
         self.updater = Updater(
             metadata_dir=metadata_dir,
             metadata_base_url=f"{base_url}/metadata/",
+            bootstrap=None,
         )
         self.updater.refresh()
 

tests/repository_simulator.py

@@ -36,8 +36,10 @@
     updater = Updater(
         dir,
         "https://example.com/metadata/",
+        dir,
         "https://example.com/targets/",
-        sim
+        sim,
+        bootstrap=sim.signed_roots[0],
     )
     updater.refresh()
 """

tests/test_updater_consistent_snapshot.py

@@ -88,6 +88,7 @@ def _init_updater(self) -> Updater:
             self.targets_dir,
             "https://example.com/targets/",
             self.sim,
+            bootstrap=self.sim.signed_roots[-1],
         )
 
     def _assert_metadata_files_exist(self, roles: Iterable[str]) -> None:

tests/test_updater_delegation_graphs.py

@@ -130,6 +130,7 @@ def _init_updater(self) -> Updater:
             self.targets_dir,
             "https://example.com/targets/",
             self.sim,
+            bootstrap=self.sim.signed_roots[0],
         )
 
     def _assert_files_exist(self, roles: Iterable[str]) -> None:

tests/test_updater_fetch_target.py

@@ -65,6 +65,7 @@ def _init_updater(self) -> Updater:
             self.targets_dir,
             "https://example.com/targets/",
             self.sim,
+            bootstrap=self.sim.signed_roots[0],
         )
 
     targets = {

tests/test_updater_key_rotations.py

@@ -79,6 +79,7 @@ def _run_refresh(self) -> None:
             self.metadata_dir,
             "https://example.com/metadata/",
             fetcher=self.sim,
+            bootstrap=self.sim.signed_roots[0],
         )
         updater.refresh()
 

tests/test_updater_ng.py

@@ -115,6 +115,7 @@ def setUp(self) -> None:
             metadata_base_url=self.metadata_url,
             target_dir=self.dl_dir,
             target_base_url=self.targets_url,
+            bootstrap=None,
         )
 
     def tearDown(self) -> None:
@@ -247,14 +248,16 @@ def test_implicit_refresh_with_only_local_root(self) -> None:
 
     def test_both_target_urls_not_set(self) -> None:
         # target_base_url = None and Updater._target_base_url = None
-        updater = Updater(self.client_directory, self.metadata_url, self.dl_dir)
+        updater = Updater(
+            self.client_directory, self.metadata_url, self.dl_dir, bootstrap=None
+        )
         info = TargetFile(1, {"sha256": ""}, "targetpath")
         with self.assertRaises(ValueError):
             updater.download_target(info)
 
     def test_no_target_dir_no_filepath(self) -> None:
         # filepath = None and Updater.target_dir = None
-        updater = Updater(self.client_directory, self.metadata_url)
+        updater = Updater(self.client_directory, self.metadata_url, bootstrap=None)
         info = TargetFile(1, {"sha256": ""}, "targetpath")
         with self.assertRaises(ValueError):
             updater.find_cached_target(info)
@@ -344,6 +347,7 @@ def test_user_agent(self) -> None:
             self.dl_dir,
             self.targets_url,
             config=UpdaterConfig(app_user_agent="MyApp/1.2.3"),
+            bootstrap=None,
         )
         updater.refresh()
         poolmgr = updater._fetcher._proxy_env.get_pool_manager(