updater: Improve comments on bootstrap arg

This includes some minor example improvements

Signed-off-by: Jussi Kukkonen <[email protected]>

Author: jku

Diff for: examples/client/client

@@ -30,15 +30,19 @@ def build_metadata_dir(base_url: str) -> str:
 
 def init_tofu(base_url: str) -> bool:
     """Initialize local trusted metadata (Trust-On-First-Use) and create a
-    directory for downloads"""
+    directory for downloads
+
+    NOTE: This is unsafe and for demonstration only: the bootstrap root
+    should be deployed alongside your updater application
+    """
 
     metadata_dir = build_metadata_dir(base_url)
 
     if not os.path.isdir(metadata_dir):
         os.makedirs(metadata_dir)
 
     data = requests.get(f"{base_url}/metadata/1.root.json").content
-    updater = Updater(
+    Updater(
         metadata_dir=metadata_dir,
         metadata_base_url=f"{base_url}/metadata/",
         target_base_url=f"{base_url}/targets/",
@@ -77,6 +81,9 @@ def download(base_url: str, target: str) -> bool:
         os.mkdir(DOWNLOAD_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.
         updater = Updater(
             metadata_dir=metadata_dir,
             metadata_base_url=f"{base_url}/metadata/",
@@ -108,7 +115,7 @@ def download(base_url: str, target: str) -> bool:
     return True
 
 
-def main() -> None:
+def main() -> str | None:
     """Main TUF Client Example function"""
 
     client_args = argparse.ArgumentParser(description="TUF Client Example")
@@ -173,6 +180,8 @@ def main() -> None:
     else:
         client_args.print_help()
 
+    return None
+
 
 if __name__ == "__main__":
     sys.exit(main())

Diff for: tuf/ngclient/updater.py

@@ -12,7 +12,8 @@
 High-level description of ``Updater`` functionality:
   * Initializing an ``Updater`` loads and validates the trusted local root
     metadata: This root metadata is used as the source of trust for all other
-    metadata.
+    metadata. Updater should always be initialized with the ``bootstrap``
+    argument: if this is not possible, it can be initialized from cache only.
   * ``refresh()`` can optionally be called to update and load all top-level
     metadata as described in the specification, using both locally cached
     metadata and metadata downloaded from the remote repository. If refresh is
@@ -81,9 +82,9 @@ class Updater:
             download both metadata and targets. Default is ``RequestsFetcher``
         config: ``Optional``; ``UpdaterConfig`` could be used to setup common
             configuration options.
-        bootstrap: ``Optional``; initial root metadata. If a boostrap root is
-            not provided then the root.json in the metadata cache is used as the
-            initial root.
+        bootstrap: ``Optional``; initial root metadata. A boostrap root should
+            always be provided. If it is not, the current root.json in the
+            metadata cache is used as the initial root.
 
     Raises:
         OSError: Local root.json cannot be read