Envelope API: rename, add docs, add alias

* Rename Envelope to SimpleEnvelope:
  Envelope should be the generic term in this context for something that
  contains a payload and signatures. SimpleEnvelope is the specific
  DSSE implementation (just like Metadata is the specific traditional
  canonical JSON -based TUF envelope implementation).

* Add SimpleEnvelope class and method docstrings.

* Add convenience alias for ``self.signatures`` mapped to keyids for
  compatibility with Metadata.signatures.

Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>

Author: Lukas Puehringer

tuf/api/dsse.py

@@ -1,11 +1,12 @@
-"""Low-level TUF Envelope API.
+"""Low-level TUF DSSE API. (experimental!)
 
 """
 import json
-from typing import Generic, Type, cast
+from typing import Dict, Generic, Type, cast
 
-from securesystemslib.dsse import Envelope as BaseEnvelope
+from securesystemslib.dsse import Envelope as BaseSimpleEnvelope
 
+# Expose all payload classes to use API independently of ``tuf.api.metadata``.
 from tuf.api._payload import (  # noqa: F401
     _ROOT,
     _SNAPSHOT,
@@ -32,25 +33,73 @@
 from tuf.api.serialization import DeserializationError, SerializationError
 
 
-class Envelope(Generic[T], BaseEnvelope):
-    """TODO: doc"""
+class SimpleEnvelope(Generic[T], BaseSimpleEnvelope):
+    """Dead Simple Signing Envelope (DSSE) for TUF payloads.
+
+    * Sign with ``self.sign()`` (inherited).
+    * Verify with ``verify_delegate`` on a ``Root`` or ``Targets``
+      object::
+
+        delegator.verify_delegate(
+            role_name,
+            envelope.pae(),  # Note, how we don't pass ``envelope.payload``!
+            envelope.signatures_dict,
+            )
+
+    Attributes:
+        payload: Serialized payload bytes.
+        payload_type: Payload string identifier.
+        signatures: List of ``Signature`` objects.
+        signatures_dict: Ordered dictionary of keyids to ``Signature`` objects.
+
+    """
 
     _DEFAULT_PAYLOAD_TYPE = "application/vnd.tuf+json"
 
+    @property
+    def signatures_dict(self) -> Dict:
+        """Convenience alias for ``self.signatures`` mapped to keyids."""
+        # TODO: Propose changing ``signatures`` list to dict upstream
+        return {sig.keyid: sig for sig in self.signatures}
+
     @classmethod
-    def from_bytes(cls, data: bytes) -> "Envelope[T]":
-        """TODO: doc"""
+    def from_bytes(cls, data: bytes) -> "SimpleEnvelope[T]":
+        """Load envelope from JSON bytes.
+
+        NOTE: Unlike ``tuf.api.metadata.Metadata.from_bytes``, this method
+        does not deserialize the contained payload. Use ``self.get_signed`` to
+        deserialize the payload into a ``Signed`` object.
+
+        Args:
+            data: envelope JSON bytes.
+
+        Raises:
+            tuf.api.serialization.DeserializationError:
+                data cannot be deserialized.
+
+        Returns:
+            TUF ``SimpleEnvelope`` object.
+        """
         try:
             envelope_dict = json.loads(data.decode())
-            envelope = Envelope.from_dict(envelope_dict)
+            envelope = SimpleEnvelope.from_dict(envelope_dict)
 
         except Exception as e:
-            raise SerializationError from e
+            raise DeserializationError from e
 
         return envelope
 
     def to_bytes(self) -> bytes:
-        """TODO: doc"""
+        """Return envelope as JSON bytes.
+
+        NOTE: Unlike ``tuf.api.metadata.Metadata.to_bytes``, this method does
+        not serialize the payload. Use ``SimpleEnvelope.from_signed`` to
+        serialize a ``Signed`` object and wrap it in an SimpleEnvelope.
+
+        Raises:
+            tuf.api.serialization.SerializationError:
+                self cannot be serialized.
+        """
         try:
             envelope_dict = self.to_dict()
             json_bytes = json.dumps(envelope_dict).encode()
@@ -61,8 +110,16 @@ def to_bytes(self) -> bytes:
         return json_bytes
 
     @classmethod
-    def from_signed(cls, signed: T) -> "Envelope[T]":
-        """TODO: doc"""
+    def from_signed(cls, signed: T) -> "SimpleEnvelope[T]":
+        """Serialize payload as JSON bytes and wrap in envelope.
+
+        Args:
+            signed: ``Signed`` object.
+
+        Raises:
+            tuf.api.serialization.SerializationError:
+                The signed object cannot be serialized.
+        """
         try:
             signed_dict = signed.to_dict()
             json_bytes = json.dumps(signed_dict).encode()
@@ -73,7 +130,13 @@ def from_signed(cls, signed: T) -> "Envelope[T]":
         return cls(json_bytes, cls._DEFAULT_PAYLOAD_TYPE, [])
 
     def get_signed(self) -> T:
-        """TODO: doc"""
+        """Extract and deserialize payload JSON bytes from envelope.
+
+        Raises:
+            tuf.api.serialization.DeserializationError:
+                The signed object cannot be deserialized.
+        """
+
         try:
             payload_dict = json.loads(self.payload.decode())
 
@@ -88,7 +151,7 @@ def get_signed(self) -> T:
             elif _type == _ROOT:
                 inner_cls = Root
             else:
-                raise ValueError(f'unrecognized metadata type "{_type}"')
+                raise ValueError(f'unrecognized role type "{_type}"')
 
         except Exception as e:
             raise DeserializationError from e

tuf/ngclient/_internal/wrapping.py

@@ -11,7 +11,7 @@
 
 from tuf.api import exceptions
 from tuf.api._payload import Root, T, Targets
-from tuf.api.dsse import Envelope
+from tuf.api.dsse import SimpleEnvelope
 from tuf.api.metadata import Metadata
 
 Delegator = Union[Root, Targets]
@@ -99,11 +99,11 @@ class EnvelopeUnwrapper(Unwrapper):
     """
 
     @staticmethod
-    def _validate_envelope_payload_type(envelope: Envelope) -> None:
+    def _validate_envelope_payload_type(envelope: SimpleEnvelope) -> None:
         # pylint: disable=protected-access
-        if envelope.payload_type != Envelope._DEFAULT_PAYLOAD_TYPE:
+        if envelope.payload_type != SimpleEnvelope._DEFAULT_PAYLOAD_TYPE:
             raise exceptions.RepositoryError(
-                f"Expected '{Envelope._DEFAULT_PAYLOAD_TYPE}', "
+                f"Expected '{SimpleEnvelope._DEFAULT_PAYLOAD_TYPE}', "
                 f"got '{envelope.payload_type}'"
             )
 
@@ -114,19 +114,17 @@ def unwrap(
         delegator: Optional[Delegator] = None,
         role_name: Optional[str] = None,
     ) -> Tuple[T, bytes, Dict[str, Signature]]:  # noqa: D102
-        envelope = Envelope[T].from_bytes(wrapper)
-
-        # TODO: Envelope stores signatures as list, but `verify_delegate`
-        # expects a dict. Should we change the envelope model?
-        signatures = {sig.keyid: sig for sig in envelope.signatures}
+        envelope = SimpleEnvelope[T].from_bytes(wrapper)
 
         self._validate_envelope_payload_type(envelope)
         if delegator:
             if role_name is None:
                 role_name = role_cls.type
-            delegator.verify_delegate(role_name, envelope.pae(), signatures)
+            delegator.verify_delegate(
+                role_name, envelope.pae(), envelope.signatures_dict
+            )
 
         signed = envelope.get_signed()
         self._validate_signed_type(signed, role_cls)
 
-        return signed, envelope.pae(), signatures
+        return signed, envelope.pae(), envelope.signatures_dict