Metadata API: Make Metadata Generic

The purpose is two-fold:
1. When we deserialize metadata, we usually know what signed type we
   expect: make it easy to enforce that
2. When we use Metadata, it is helpful if the specific signed type (and
   all of the classes attribute types are correctly annotated

Making Metadata Generic over T, where

    T = TypeVar("T", "Root", "Timestamp", "Snapshot", "Targets")

allows both of these cases to work. Using Generics is completely
optional so all existing code still works. For case 1, the following
calls will now raise a Deserialization error if the expected type is
incorrect:

    md = Metadata.from_bytes(data, signed_type=Snapshot)
    md = Metadata.from_file(filename, signed_type=Snapshot)

For case 2, the return value md of those calls is now of type
"Metadata[Snapshot]", and md.signed is now of type "Snapshot" allowing
IDE annotations and static type checking.

Adding a type argument is an unconventional way to do this: the reason
for it is that the specific type (e.g. Snapshot) is not otherwise
available at runtime. A call like this works fine and md is annotated:

    md = Metadata[Snapshot].from_bytes(data)

but it's not possible to validate that "data" contains a "Snapshot",
because the value "Snapshot" is not defined at runtime at all, it is
purely an annotation. So an actual argument is needed.

Fixes #1433

Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>

Author: Jussi Kukkonen

tests/test_api.py

@@ -134,6 +134,23 @@ def test_generic_read(self):
         os.remove(bad_metadata_path)
 
 
+    def test_typed_read(self):
+        path = os.path.join(self.repo_dir, 'metadata', 'root.json')
+        with open(path, 'rb') as f:
+            data = f.read()
+
+        # Loading a root file as "Metadata[Root]" succeeds
+        md = Metadata.from_bytes(data, signed_type=Root)
+        md2 = Metadata.from_file(path, signed_type=Root)
+
+        # Loading the file fails with non-"Root" type constraints
+        for expected_type in [Timestamp, Snapshot, Targets]:
+            with self.assertRaises(DeserializationError):
+                Metadata.from_bytes(data, signed_type=expected_type)
+            with self.assertRaises(DeserializationError):
+                Metadata.from_file(path, signed_type=expected_type)
+
+
     def test_compact_json(self):
         path = os.path.join(self.repo_dir, 'metadata', 'targets.json')
         metadata_obj = Metadata.from_file(path)

tuf/api/metadata.py

@@ -25,12 +25,15 @@
     BinaryIO,
     ClassVar,
     Dict,
+    Generic,
     List,
     Mapping,
     Optional,
     Tuple,
     Type,
+    TypeVar,
     Union,
+    cast,
 )
 
 from securesystemslib import hash as sslib_hash
@@ -41,6 +44,7 @@
 
 from tuf import exceptions
 from tuf.api.serialization import (
+    DeserializationError,
     MetadataDeserializer,
     MetadataSerializer,
     SignedSerializer,
@@ -55,8 +59,11 @@
 # files to have the same major version (the first number) as ours.
 SPECIFICATION_VERSION = ["1", "0", "19"]
 
+# T is a Generic type constraint for Metadata.signed
+T = TypeVar("T", "Root", "Timestamp", "Snapshot", "Targets")
 
-class Metadata:
+
+class Metadata(Generic[T]):
     """A container for signed TUF metadata.
 
     Provides methods to convert to and from dictionary, read and write to and
@@ -73,7 +80,8 @@ class Metadata:
     def __init__(
         self, signed: "Signed", signatures: "OrderedDict[str, Signature]"
     ):
-        self.signed = signed
+        # init does not verify type constraint T: only from_bytes() does
+        self.signed: T = cast(T, signed)
         self.signatures = signatures
 
     @classmethod
@@ -123,13 +131,13 @@ def from_dict(cls, metadata: Dict[str, Any]) -> "Metadata":
             signatures=signatures,
         )
 
-    @classmethod
+    @staticmethod
     def from_file(
-        cls,
         filename: str,
         deserializer: Optional[MetadataDeserializer] = None,
         storage_backend: Optional[StorageBackendInterface] = None,
-    ) -> "Metadata":
+        signed_type: Optional[Type[T]] = None,
+    ) -> "Metadata[T]":
         """Loads TUF metadata from file storage.
 
         Arguments:
@@ -140,6 +148,7 @@ def from_file(
             storage_backend: An object that implements
                 securesystemslib.storage.StorageBackendInterface. Per default
                 a (local) FilesystemBackend is used.
+            signed_type: Optional; Expected type of deserialized signed object.
 
         Raises:
             securesystemslib.exceptions.StorageError: The file cannot be read.
@@ -153,20 +162,22 @@ def from_file(
         if storage_backend is None:
             storage_backend = FilesystemBackend()
 
-        with storage_backend.get(filename) as file_obj:
-            return cls.from_bytes(file_obj.read(), deserializer)
+        with storage_backend.get(filename) as f:
+            return Metadata.from_bytes(f.read(), deserializer, signed_type)
 
     @staticmethod
     def from_bytes(
         data: bytes,
         deserializer: Optional[MetadataDeserializer] = None,
-    ) -> "Metadata":
+        signed_type: Optional[Type[T]] = None,
+    ) -> "Metadata[T]":
         """Loads TUF metadata from raw data.
 
         Arguments:
             data: metadata content as bytes.
             deserializer: Optional; A MetadataDeserializer instance that
                 implements deserialization. Default is JSONDeserializer.
+            signed_type: Optional; Expected type of deserialized signed object.
 
         Raises:
             tuf.api.serialization.DeserializationError:
@@ -183,7 +194,14 @@ def from_bytes(
 
             deserializer = JSONDeserializer()
 
-        return deserializer.deserialize(data)
+        md = deserializer.deserialize(data)
+
+        # Ensure deserialized signed type matches the requested type
+        if signed_type is not None and signed_type != type(md.signed):
+            raise DeserializationError(
+                f"Expected {signed_type}, got {type(md.signed)}"
+            )
+        return md
 
     def to_dict(self) -> Dict[str, Any]:
         """Returns the dict representation of self."""