joserfc 0.1.0__tar.gz

joserfc-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Hsiaoming Yang
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

joserfc-0.1.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.1
+Name: joserfc
+Version: 0.1.0
+Summary: The ultimate Python library for JOSE RFCs, including JWS, JWE, JWK, JWA, JWT
+Author-email: Hsiaoming Yang <me@lepture.com>
+License: BSD 3-Clause License
+        
+        Copyright (c) 2023, Hsiaoming Yang
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: Documentation, https://jose.authlib.org/
+Project-URL: Blog, https://blog.authlib.org/
+Requires-Python: >=3.8
+License-File: LICENSE

joserfc-0.1.0/README.md

@@ -0,0 +1,3 @@
+# JOSE RFCs
+
+The Python implementations of JOSE RFCs.

joserfc-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "joserfc"
+description = "The ultimate Python library for JOSE RFCs, including JWS, JWE, JWK, JWA, JWT"
+authors = [{name = "Hsiaoming Yang", email="me@lepture.com"}]
+dependencies = [
+  "cryptography",
+]
+license = {file = "LICENSE"}
+requires-python = ">=3.8"
+dynamic = ["version"]
+
+[project.urls]
+Documentation = "https://jose.authlib.org/"
+Blog = "https://blog.authlib.org/"
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.dynamic]
+version = {attr = "joserfc.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src", "."]
+testpaths = ["tests"]
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+branch = true
+source = ["joserfc"]
+
+[tool.coverage.paths]
+source = ["src"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "pragma: no cover",
+  "raise NotImplementedError",
+  "@(abc\\.)?abstractmethod",
+]

joserfc-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

joserfc-0.1.0/src/joserfc/__init__.py

@@ -0,0 +1,5 @@
+
+__version__ = "0.1.0"
+__homepage__ = "https://jose.authlib.org/"
+__author__ = "Hsiaoming Yang <me@lepture.com>"
+__license__ = "BSD-3-Clause"

joserfc-0.1.0/src/joserfc/errors.py

@@ -0,0 +1,88 @@
+from typing import Optional
+
+
+class JoseError(Exception):
+    """Base Exception for all errors in joserfc."""
+
+    #: short-string error code
+    error: str = ''
+    #: long-string to describe this error
+    description: str = ''
+
+    def __init__(self, description: Optional[str]=None, error: Optional[str]=None):
+        if error is not None:
+            self.error = error
+        if description is not None:
+            self.description = description
+
+        message = '{}: {}'.format(self.error, self.description)
+        super(JoseError, self).__init__(message)
+
+    def __repr__(self):
+        return '<{} "{}">'.format(self.__class__.__name__, self.error)
+
+
+class DecodeError(JoseError):
+    error: str = 'decode_error'
+
+
+class MissingAlgorithmError(JoseError):
+    error: str = 'missing_algorithm'
+    description: str = 'Missing "alg" value in header'
+
+
+class MissingEncryptionError(JoseError):
+    error: str = 'missing_encryption'
+    description: str = 'Missing "enc" value in header'
+
+
+class InvalidKeyManagementModeError(JoseError):
+    error: str = 'invalid_key_management_mode'
+    description: str = ''
+
+
+class BadSignatureError(JoseError):
+    error: str = 'bad_signature'
+
+
+class InvalidClaimError(JoseError):
+    error: str = 'invalid_claim'
+
+    def __init__(self, claim):
+        description = f'Invalid claim: "{claim}"'
+        super(InvalidClaimError, self).__init__(description=description)
+
+
+class MissingClaimError(JoseError):
+    error: str = 'missing_claim'
+
+    def __init__(self, claim):
+        description = f'Missing claim: "{claim}"'
+        super(MissingClaimError, self).__init__(description=description)
+
+
+class InsecureClaimError(JoseError):
+    error: str = 'insecure_claim'
+
+    def __init__(self, claim):
+        description = f'Insecure claim "{claim}"'
+        super(InsecureClaimError, self).__init__(description=description)
+
+
+class ExpiredTokenError(JoseError):
+    error: str = 'expired_token'
+    description: str = 'The token is expired'
+
+
+class InvalidTokenError(JoseError):
+    error: str = 'invalid_token'
+    description: str = 'The token is not valid yet'
+
+
+class InvalidTypeError(JoseError):
+    error: str = 'invalid_type'
+    description: str = 'The "typ" value in header is invalid'
+
+
+class InvalidPayloadError(JoseError):
+    error: str = 'invalid_payload'

joserfc-0.1.0/src/joserfc/jwe.py

@@ -0,0 +1,70 @@
+from typing import Optional, AnyStr
+from .rfc7516 import types
+from .rfc7516.types import Header, EncryptionData, Recipient
+from .rfc7516.registry import (
+    JWERegistry,
+    default_registry,
+)
+from .rfc7516.message import perform_encrypt, perform_decrypt
+from .rfc7516.compact import represent_compact, extract_compact
+from .rfc7518.jwe_algs import JWE_ALG_MODELS
+from .rfc7518.jwe_encs import JWE_ENC_MODELS
+from .rfc7518.jwe_zips import JWE_ZIP_MODELS
+from .jwk import KeyFlexible, guess_key
+from .util import to_bytes
+
+
+__all__ = [
+    'types',
+    'JWERegistry',
+    'encrypt_compact',
+    'decrypt_compact',
+    'extract_compact',
+]
+
+def __register():
+    for _alg in JWE_ALG_MODELS:
+        JWERegistry.register(_alg)
+
+    for _enc in JWE_ENC_MODELS:
+        JWERegistry.register(_enc)
+
+    for _zip in JWE_ZIP_MODELS:
+        JWERegistry.register(_zip)
+
+__register()
+
+
+def encrypt_compact(
+        protected: Header,
+        payload: bytes,
+        public_key: KeyFlexible,
+        registry: Optional[JWERegistry]=None) -> bytes:
+
+    if registry is None:
+        registry = default_registry
+
+    obj = EncryptionData(protected, payload)
+    recipient = Recipient(obj)
+    key = guess_key(public_key, recipient)
+    recipient.recipient_key = key
+    obj.recipients.append(recipient)
+    obj.compact = True
+    perform_encrypt(obj, registry)
+    return represent_compact(obj)
+
+
+def decrypt_compact(
+        value: AnyStr,
+        private_key: KeyFlexible,
+        registry: Optional[JWERegistry]=None) -> EncryptionData:
+
+    value = to_bytes(value)
+    obj = extract_compact(value)
+    if registry is None:
+        registry = default_registry
+
+    recipient = obj.recipients[0]
+    key = guess_key(private_key, recipient)
+    recipient.recipient_key = key
+    return perform_decrypt(obj, registry)

joserfc-0.1.0/src/joserfc/jwk.py

@@ -0,0 +1,86 @@
+import random
+from typing import Callable, Union, Any, Protocol
+from .rfc7517 import (
+    SymmetricKey,
+    AsymmetricKey,
+    Key,
+    KeySet,
+    JWK_REGISTRY,
+)
+from .rfc7517.keygen import (
+    import_key,
+    generate_key,
+)
+from .rfc7517 import types
+from .rfc7518.oct_key import OctKey
+from .rfc7518.rsa_key import RSAKey
+from .rfc7518.ec_key import ECKey
+from .rfc8037.okp_key import OKPKey
+from .rfc8812 import register_secp256k1
+from .registry import Header
+
+
+KeyCallable = Callable[[Any, bool], Key]
+KeyFlexible = Union[Key, KeySet, KeyCallable]
+
+__all__ = [
+    'types',
+    'JWK_REGISTRY',
+    'SymmetricKey',
+    'AsymmetricKey',
+    'Key',
+    'KeyCallable',
+    'KeyFlexible',
+    'OctKey',
+    'RSAKey',
+    'ECKey',
+    'OKPKey',
+    'KeySet',
+    'generate_key',
+    'import_key',
+    'guess_key',
+]
+
+# register thumbprint method
+register_secp256k1()
+
+# register all key types
+JWK_REGISTRY[OctKey.key_type] = OctKey
+JWK_REGISTRY[RSAKey.key_type] = RSAKey
+JWK_REGISTRY[ECKey.key_type] = ECKey
+JWK_REGISTRY[OKPKey.key_type] = OKPKey
+
+
+class GuestProtocol(Protocol):
+    def headers(self) -> Header:
+        ...
+
+    def set_kid(self, kid: str):
+        ...
+
+
+def guess_key(key: KeyFlexible, obj: GuestProtocol) -> Key:
+    """Guess key from a various sources.
+
+    :param key: a very flexible key
+    :param obj: a protocol that has ``headers`` and ``set_kid`` methods
+    """
+    if isinstance(key, (SymmetricKey, AsymmetricKey)):
+        return key
+
+    elif isinstance(key, KeySet):
+        headers = obj.headers()
+        kid = headers.get('kid')
+
+        if not kid:
+            # choose one key by random
+            key: Key = random.choice(key.keys)
+            # use side effect to add kid information
+            obj.set_kid(key.kid)
+            return key
+        return key.get_by_kid(kid)
+
+    elif callable(key):
+        return key(obj)
+
+    raise ValueError("Invalid key")

joserfc-0.1.0/src/joserfc/jws.py

@@ -0,0 +1,192 @@
+from typing import Optional, AnyStr, List, Union
+from .rfc7515 import types
+from .rfc7515.model import JWSAlgModel
+from .rfc7515.registry import (
+    JWSRegistry,
+    default_registry,
+)
+from .rfc7515.compact import (
+    sign_compact,
+    extract_compact,
+    verify_compact,
+)
+from .rfc7515.json import (
+    sign_json,
+    verify_json,
+    extract_json,
+)
+from .rfc7515.types import (
+    Header,
+    HeaderMember,
+    HeaderDict,
+    SignatureData,
+    JSONSerialization,
+)
+from .rfc7518.jws_algs import JWS_ALGORITHMS
+from .rfc8037.jws_eddsa import EdDSA
+from .rfc8812 import ES256K
+from .errors import BadSignatureError
+from .jwk import Key, KeyFlexible, guess_key
+from .util import to_bytes, urlsafe_b64encode
+
+__all__ = [
+    'types',
+    'JWSAlgModel',
+    'JWSRegistry',
+    'SignatureData',
+
+    'serialize_compact',
+    'deserialize_compact',
+    'extract_compact',
+    'validate_compact',
+
+    'serialize_json',
+    'deserialize_json',
+    'extract_json',
+    'validate_json',
+]
+
+# register supported alg models
+def __register():
+    # register alg in RFC7518
+    for _alg in JWS_ALGORITHMS:
+        JWSRegistry.register(_alg)
+    # register alg in RFC8037
+    JWSRegistry.register(EdDSA)
+    # register alg in RFC8812
+    JWSRegistry.register(ES256K)
+
+__register()
+
+
+def serialize_compact(
+        header: Header,
+        payload: bytes,
+        key: KeyFlexible,
+        registry: Optional[JWSRegistry]=None) -> bytes:
+    """Generate a JWS Compact Serialization. The JWS Compact Serialization
+    represents digitally signed or MACed content as a compact, URL-safe
+    string, per Section 7.1.
+
+    .. code-block:: text
+
+        BASE64URL(UTF8(JWS Protected Header)) || '.' ||
+        BASE64URL(JWS Payload) || '.' ||
+        BASE64URL(JWS Signature)
+
+    :param header: protected header part of the JWS, in dict
+    :param payload: payload data of the JWS, in bytes
+    :param key: a flexible private key to sign the signature
+    :param registry: a JWSRegistry to use
+    :return: JWS in bytes
+
+    .. note:: The returned value is in bytes
+    """
+    if registry is None:
+        registry = default_registry
+
+    registry.check_header(header)
+    member = HeaderMember(header)
+    obj = SignatureData([member], payload)
+    obj.compact = True
+    alg: JWSAlgModel = registry.get_alg(header['alg'])
+    key: Key = guess_key(key, member)
+    return sign_compact(obj, alg, key)
+
+
+def validate_compact(
+        obj: SignatureData,
+        key: KeyFlexible,
+        registry: Optional[JWSRegistry]=None):
+    """Validate the JWS Compact Serialization with the given key.
+    This method is usually used together with ``extract_compact``.
+
+    :param obj: object of the JWS Compact Serialization
+    :param key: a flexible public key to verify the signature
+    :param registry: a JWSRegistry to use
+    :raise: ValueError or BadSignatureError
+    """
+    if registry is None:
+        registry = default_registry
+    member = obj.members[0]
+    alg: JWSAlgModel = registry.get_alg(member.protected['alg'])
+    key: Key = guess_key(key, member)
+    if not verify_compact(obj, alg, key):
+        raise BadSignatureError()
+
+
+def deserialize_compact(
+        value: AnyStr,
+        key: KeyFlexible,
+        registry: Optional[JWSRegistry]=None) -> SignatureData:
+    """Extract and validate the JWS (in string) with the given key.
+
+    :param value: a string (or bytes) of the JWS
+    :param key: a flexible public key to verify the signature
+    :param registry: a JWSRegistry to use
+    :return: object of the JWS Compact Serialization
+    """
+    obj = extract_compact(to_bytes(value))
+    validate_compact(obj, key, registry)
+    return obj
+
+
+def serialize_json(
+        members: Union[HeaderDict, List[HeaderDict]],
+        payload: bytes,
+        key: KeyFlexible,
+        registry: Optional[JWSRegistry]=None) -> JSONSerialization:
+    if registry is None:
+        registry = default_registry
+
+    if isinstance(members, dict):
+        flatten = True
+        registry.check_header(members['protected'])
+        members = [members]
+    else:
+        flatten = False
+        for member in members:
+            registry.check_header(member['protected'])
+
+    members = [HeaderMember(**member) for member in members]
+    obj = SignatureData(members, payload)
+    obj.segments['payload'] = urlsafe_b64encode(payload)
+    obj.flatten = flatten
+
+    find_key = lambda d: guess_key(key, d)
+    return sign_json(obj, registry.get_alg, find_key)
+
+
+def validate_json(
+        obj: SignatureData,
+        key: KeyFlexible,
+        registry: Optional[JWSRegistry]=None):
+    """Validate the JWS JSON Serialization with the given key.
+    This method is usually used together with ``extract_json``.
+
+    :param obj: object of the JWS JSON Serialization
+    :param key: a flexible public key to verify the signature
+    :param registry: a JWSRegistry to use
+    :raise: ValueError or BadSignatureError
+    """
+    if registry is None:
+        registry = default_registry
+    find_key = lambda d: guess_key(key, d)
+    if not verify_json(obj, registry.get_alg, find_key):
+        raise BadSignatureError()
+
+
+def deserialize_json(
+        value: JSONSerialization,
+        key: KeyFlexible,
+        registry: Optional[JWSRegistry]=None) -> SignatureData:
+    """Extract and validate the JWS (in string) with the given key.
+
+    :param value: a dict of the JSON signature
+    :param key: a flexible public key to verify the signature
+    :param registry: a JWSRegistry to use
+    :return: object of the SignatureData
+    """
+    obj = extract_json(value)
+    validate_json(obj, key, registry)
+    return obj

joserfc-0.1.0/src/joserfc/jwt.py

@@ -0,0 +1,79 @@
+from typing import Optional, AnyStr
+from .rfc7515.compact import extract_compact
+from .rfc7519.claims import Claims, convert_claims
+from .rfc7519.validators import ClaimsOption, JWTClaimsRequests
+from .rfc7519.registry import JWTRegistry, default_registry
+from .jws import serialize_compact, validate_compact
+from .jwk import KeyFlexible
+from .errors import InvalidTypeError, InvalidPayloadError
+from .util import to_bytes
+from .registry import Header
+
+
+__all__ = [
+    'Header',
+    'Claims',
+    'Token',
+    'ClaimsOption',
+    'JWTRegistry',
+    'JWTClaimsRequests',
+    'encode',
+    'decode',
+]
+
+
+class Token:
+    def __init__(self, header: Header, claims: Claims):
+        self.header = header
+        self.claims = claims
+
+
+def encode(
+        header: Header,
+        claims: Claims,
+        key: KeyFlexible,
+        registry: Optional[JWTRegistry]=None) -> str:
+    """Encode a JSON Web Token with the given header, and claims.
+
+    :param header: A dict of the JWT header
+    :param claims: A dict of the JWT claims to be encoded
+    :param key: key used to sign the signature
+    :param registry: a JWTRegistry to use
+    """
+    # add ``typ`` in header
+    header['typ'] = 'JWT'
+    payload = convert_claims(claims)
+    if registry is None:
+        registry = default_registry
+    result = serialize_compact(header, payload, key, registry)
+    return result.decode('utf-8')
+
+
+def decode(
+        value: AnyStr,
+        key: KeyFlexible,
+        registry: Optional[JWTRegistry]=None) -> Token:
+    """Decode the JSON Web Token string with the given key, and validate
+    it with the claims requests. This method is a combination of the
+    :function:`extract` and :function:`validate`.
+
+    :param value: text of the JWT
+    :param key: key used to verify the signature
+    :param registry: a JWTRegistry to use
+    :raise: BadSignatureError
+    """
+    obj = extract_compact(to_bytes(value))
+    try:
+        token = Token(obj.headers(), obj.claims)
+    except ValueError:
+        raise InvalidPayloadError('Payload should be a JSON dict')
+    if registry is None:
+        registry = default_registry
+
+    typ = token.header.get('typ')
+    if typ and typ != 'JWT':
+        raise InvalidTypeError()
+
+    registry.check_claims(token.claims)
+    validate_compact(obj, key, registry)
+    return token