Add type definitions and annotations (#4)

I'm not sure if this is the best way to define the types (should they inherit from the types in nacl.signing?) but the main objective is to define stable names which can be referenced in applications.

Author: richvdh

setup.py

@@ -48,6 +48,8 @@ def exec_file(path_segments, name):
         "canonicaljson>=1.0.0",
         "unpaddedbase64>=1.0.1",
         "pynacl>=0.3.0",
+        "typing_extensions>=3.5",
+        'typing>=3.5;python_version<"3.5"',
     ],
     long_description=read_file(("README.rst",)),
     keywords="json",

signedjson/__init__.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = "1.0.0"
+__version__ = "1.1-dev1"

signedjson/key.py

@@ -1,14 +1,36 @@
-from unpaddedbase64 import encode_base64, decode_base64
+# -*- coding: utf-8 -*-
+
+# Copyright 2014 OpenMarket Ltd
+# Copyright 2020 The Matrix.org Foundation C.I.C
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Iterable, List, TextIO
+
 import nacl.signing
+from unpaddedbase64 import decode_base64, encode_base64
+
+from signedjson.types import SigningKey, VerifyKey
 
 NACL_ED25519 = "ed25519"
 SUPPORTED_ALGORITHMS = [NACL_ED25519]
 
 
 def generate_signing_key(version):
+    # type: (str) -> SigningKey
     """Generate a new signing key
     Args:
-        version (str): Identifies this key out the keys for this entity.
+        version: Identifies this key out the keys for this entity.
     Returns:
         A SigningKey object.
     """
@@ -19,6 +41,7 @@ def generate_signing_key(version):
 
 
 def get_verify_key(signing_key):
+    # type: (SigningKey) -> VerifyKey
     """Get a verify key from a signing key"""
     verify_key = signing_key.verify_key
     verify_key.version = signing_key.version
@@ -27,11 +50,12 @@ def get_verify_key(signing_key):
 
 
 def decode_signing_key_base64(algorithm, version, key_base64):
+    # type: (str, str, bytes) -> SigningKey
     """Decode a base64 encoded signing key
     Args:
-        algorithm (str): The algorithm the key is for (currently "ed25519").
-        version (str): Identifies this key out of the keys for this entity.
-        key_base64 (str): Base64 encoded bytes of the key.
+        algorithm: The algorithm the key is for (currently "ed25519").
+        version: Identifies this key out of the keys for this entity.
+        key_base64: Base64 encoded bytes of the key.
     Returns:
         A SigningKey object.
     """
@@ -46,26 +70,29 @@ def decode_signing_key_base64(algorithm, version, key_base64):
 
 
 def encode_signing_key_base64(key):
+    # type: (SigningKey) -> str
     """Encode a signing key as base64
     Args:
-        key (SigningKey): A signing key to encode.
+        key: A signing key to encode.
     Returns:
         base64 encoded string.
     """
     return encode_base64(key.encode())
 
 
 def encode_verify_key_base64(key):
+    # type: (VerifyKey) -> str
     """Encode a verify key as base64
     Args:
-        key (VerifyKey): A signing key to encode.
+        key: A signing key to encode.
     Returns:
         base64 encoded string.
     """
     return encode_base64(key.encode())
 
 
 def is_signing_algorithm_supported(key_id):
+    # type: (str) -> bool
     """Is the signing algorithm for this key_id supported"""
     if key_id.startswith(NACL_ED25519 + ":"):
         return True
@@ -74,10 +101,11 @@ def is_signing_algorithm_supported(key_id):
 
 
 def decode_verify_key_bytes(key_id, key_bytes):
+    # type: (str, bytes) -> VerifyKey
     """Decode a raw verify key
     Args:
-        key_id (str): Identifies this key out of the keys for this entity.
-        key_bytes (str): Raw bytes of the key.
+        key_id: Identifies this key out of the keys for this entity.
+        key_bytes: Raw bytes of the key.
     Returns:
         A VerifyKey object.
     """
@@ -92,6 +120,7 @@ def decode_verify_key_bytes(key_id, key_bytes):
 
 
 def read_signing_keys(stream):
+    # type: (Iterable[str]) -> List[SigningKey]
     """Reads a list of keys from a stream
     Args:
         stream : A stream to iterate for keys.
@@ -107,6 +136,7 @@ def read_signing_keys(stream):
 
 
 def read_old_signing_keys(stream):
+    # type: (Iterable[str]) -> List[VerifyKey]
     """Reads a list of old keys from a stream
     Args:
         stream : A stream to iterate for keys.
@@ -124,6 +154,7 @@ def read_old_signing_keys(stream):
 
 
 def write_signing_keys(stream, keys):
+    # type: (TextIO, Iterable[SigningKey]) -> None
     """Writes a list of keys to a stream.
     Args:
         stream: Stream to write keys to.

signedjson/sign.py

@@ -1,6 +1,7 @@
 # -*- coding: utf-8 -*-
 
 # Copyright 2014 OpenMarket Ltd
+# Copyright 2020 The Matrix.org Foundation C.I.C
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,16 +15,23 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from canonicaljson import encode_canonical_json
-from unpaddedbase64 import encode_base64, decode_base64
-from signedjson.key import SUPPORTED_ALGORITHMS
 
 import logging
+from typing import Any, Dict, Iterable, List
+
+from canonicaljson import encode_canonical_json
+from unpaddedbase64 import decode_base64, encode_base64
+
+from signedjson.key import SUPPORTED_ALGORITHMS
+from signedjson.types import SigningKey, VerifyKey
 
 logger = logging.getLogger(__name__)
 
+JsonDict = Dict[str, Any]
+
 
 def sign_json(json_object, signature_name, signing_key):
+    # type: (JsonDict, str, SigningKey) -> JsonDict
     """Sign the JSON object. Stores the signature in json_object["signatures"].
 
     Args:
@@ -55,6 +63,7 @@ def sign_json(json_object, signature_name, signing_key):
 
 def signature_ids(json_object, signature_name,
                   supported_algorithms=SUPPORTED_ALGORITHMS):
+    # type: (JsonDict, str, Iterable[str]) -> List[str]
     """Does the JSON object have a signature for the given name?
     Args:
         json_object (dict): The JSON object to check.
@@ -77,15 +86,16 @@ class SignatureVerifyException(Exception):
 
 
 def verify_signed_json(json_object, signature_name, verify_key):
+    # type: (JsonDict, str, VerifyKey) -> None
     """Check a signature on a signed JSON object.
 
     Args:
-        json_object (dict): The signed JSON object to check.
-        signature_name (str): The name of the signature to check.
-        verify_key (syutil.crypto.VerifyKey): The key to verify the signature.
+        json_object: The signed JSON object to check.
+        signature_name: The name of the signature to check.
+        verify_key: The key to verify the signature.
 
     Raises:
-        InvalidSignature: If the signature isn't valid
+        SignatureVerifyException: If the signature isn't valid
     """
 
     try:

signedjson/types.py

@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+# Copyright 2020 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import nacl.signing
+from typing_extensions import Protocol
+
+
+class BaseKey(Protocol):
+    """Common base type for VerifyKey and SigningKey"""
+    version = ""  # type: str
+    alg = ""  # type: str
+
+    def encode(self):
+        # type: () -> bytes
+        pass   # pragma: nocover
+
+
+class VerifyKey(BaseKey):
+    """The public part of a key pair, for use with verify_signed_json"""
+    def verify(self, message, signature):
+        # type: (bytes, bytes) -> bytes
+        pass   # pragma: nocover
+
+
+class SigningKey(BaseKey):
+    """The private part of a key pair, for use with sign_json"""
+    def sign(self, message):
+        # type: (bytes) -> nacl.signing.SignedMessage
+        pass   # pragma: nocover
+
+    @property
+    def verify_key(self):
+        # type: () -> nacl.signing.VerifyKey
+        pass   # pragma: nocover