reshut 0.0.3__py3-none-any.whl

reshut/__init__.py

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: © 2026 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+__version__ = '0.0.3'
+__commit__ = '7ac5fb9'
+__all__ = [
+    '__version__', '__commit__',
+    'authorization',
+    'middleware',
+    'utils'
+]

reshut/__main__.py

@@ -0,0 +1,113 @@
+# SPDX-FileCopyrightText: © 2026 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import argparse
+import json
+import sys
+from typing import Optional
+from pathlib import Path
+
+from .utils import Algorithm, keygen, tokenize, validate
+
+
+def __write_key_files(basename:str, prikey:str, pubkey:Optional[str]) -> None:
+    base_path = Path(basename)
+    if pubkey is None:
+        # shared secret
+        out_path = base_path.with_suffix('.b64')
+        out_path.write_text(prikey, encoding='utf-8')
+        print(f'Wrote secret key to {out_path}')
+    else:
+        # keypair
+        prikey_path = base_path.with_name(f'{base_path.name}_prikey.pem')
+        pubkey_path = base_path.with_name(f'{base_path.name}_pubkey.pem')
+        prikey_path.write_text(prikey, encoding='utf-8')
+        print(f'Wrote private key to {prikey_path}')
+        pubkey_path.write_text(pubkey, encoding='utf-8')
+        print(f'Wrote public  key to {pubkey_path}')
+
+def __cmd_keygen(args: argparse.Namespace) -> None:
+    try:
+        alg = Algorithm(str(args.type).upper())
+    except ValueError as exc:
+        sys.stderr.write(f'Unsupported algorithm: {args.type}\n')
+        raise SystemExit(2) from exc
+
+    prikey, pubkey = keygen(alg)          # type: ignore[arg-type]
+    __write_key_files(args.output, prikey, pubkey)
+
+
+def __read_key_file(path: Path) -> str:
+    try:
+        return path.read_text(encoding='utf-8').strip()
+    except OSError as exc:
+        sys.stderr.write(f'Unable to read key file {path}: {exc}\n')
+        raise SystemExit(3) from exc
+
+
+def __cmd_tokenize(args: argparse.Namespace) -> None:
+    try:
+        alg = Algorithm(str(args.type).upper())
+    except ValueError as exc:
+        sys.stderr.write(f'Unsupported algorithm: {args.type}\n')
+        raise SystemExit(4) from exc
+    try:
+        claims = json.loads(args.claims)
+        if not isinstance(claims, dict):
+            raise TypeError
+    except Exception as exc:
+        sys.stderr.write('Claims must be a JSON object.\n')
+        raise SystemExit(5) from exc
+    private_key = __read_key_file(Path(args.key))
+    token = tokenize(alg, private_key, claims)
+    print(token)
+
+
+def __cmd_validate(args: argparse.Namespace) -> None:
+    try:
+        alg = Algorithm(str(args.type).upper())
+    except ValueError as exc:
+        sys.stderr.write(f'Unsupported algorithm: {args.type}\n')
+        raise SystemExit(6) from exc
+    public_key = __read_key_file(Path(args.key))
+    try:
+        claims = validate(alg, public_key, args.token)
+    except Exception as exc:
+        sys.stderr.write(f'Validation failed: {exc}\n')
+        raise SystemExit(7) from exc
+
+    print(json.dumps(claims, indent=2, sort_keys=True))
+
+
+def main(argv:list[str]) -> None:
+    parser = argparse.ArgumentParser(
+        prog='python -m reshut',
+        description='Utility for generating keys, creating and validating JWTs.'
+    )
+    subparsers = parser.add_subparsers(dest='command', required=True)
+
+    # reshut-keygen
+    reshut_keygen = subparsers.add_parser('keygen', help='Generate a secret or key‑pair.')
+    reshut_keygen.add_argument('--type', required=True, help='Algorithm name (e.g. HS256, RS256).')
+    reshut_keygen.add_argument('--output', required=True, help='Base filename (prefix) for generated key files.')
+    reshut_keygen.set_defaults(func=__cmd_keygen)
+
+    # reshut-tokenize
+    reshut_tokenize = subparsers.add_parser('tokenize', help='Create a JWT from claims.')
+    reshut_tokenize.add_argument('--type', required=True, help='Algorithm name.')
+    reshut_tokenize.add_argument('--claims', required=True, help='JSON string representing the claim set.')
+    reshut_tokenize.add_argument('--key', required=True, help='Path to the private key / secret file.')
+    reshut_tokenize.set_defaults(func=__cmd_tokenize)
+
+    # reshut-validate
+    reshut_validate = subparsers.add_parser('validate', help='Validate a JWT.')
+    reshut_validate.add_argument('--type', required=True, help='Algorithm name.')
+    reshut_validate.add_argument('--token', required=True, help='JWT string to validate.')
+    reshut_validate.add_argument('--key', required=True, help='Path to the public key / secret file.')
+    reshut_validate.set_defaults(func=__cmd_validate)
+
+    args = parser.parse_args(argv)
+    args.func(args)          # type: ignore[attr-defined]
+
+if __name__ == '__main__':
+    main(sys.argv[1:])

reshut/authorization.py

@@ -0,0 +1,85 @@
+# SPDX-FileCopyrightText: © 2026 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import inspect
+from typing import Any, Callable, Optional, TypeAlias, cast
+
+ClaimEvaluator:TypeAlias = Callable[[Any], bool]
+
+
+def allow_anonymous(func:Callable[..., Any]) -> Callable[..., Any]:
+    """
+    Indicates that a handler does not require Authorization.
+
+    :param func: The handler function.
+    :return: The handler function (not wrapped.)
+    """
+    org = inspect.unwrap(func)
+    setattr(org, '__reshut_noauth', True)
+    return func
+
+def allow_claim(func:Callable[..., Any], claim_name:str, claim_check:Optional[Any|ClaimEvaluator] = None, is_required:bool = False) -> Callable[..., Any]:
+    """
+    Adds an ALLOW claim rule to a handler.
+    
+    When at least one ALLOW claim rule is defined on a handler, then access is denied if at least one of the allowed claims is not presented.
+
+    :param func: The handler function.
+    :param claim_name: Claim name.
+    :param claim_check: Optional literal value that the claim must present, or a ``ClaimEvaluator`` that checks the claim is a match.
+    :param is_required: Optional boolean indicating that the claim is required, forming a "REQUIRED claim rule".
+    :return: The handler function (not wrapped.)
+    """
+    bag_name = '__reshut_require' if is_required else '__reshut_allow'
+    org = inspect.unwrap(func)
+    if not hasattr(org, bag_name):
+        setattr(org, bag_name, dict[str,Any]({
+            claim_name: claim_check
+        }))
+    else:
+        allow_list = cast(dict[str,Any],getattr(org, bag_name))
+        allow_list[claim_name] = claim_check
+    return func
+
+def deny_claim(func:Callable[..., Any], claim_name:str, claim_check:Optional[Any|ClaimEvaluator] = None) -> Callable[..., Any]:
+    """
+    Adds a DENY claim rule to a handler.
+
+    When any presented claim matches a DENY claim rule, then access is denied.
+
+    :param func: The handler function.
+    :param claim_name: Claim name.
+    :param claim_check: Optional literal value that the claim must NOT present, or a ``ClaimEvaluator`` that checks the claim is a match.
+    :return: The handler function (not wrapped.)
+    """
+    org = inspect.unwrap(func)
+    if not hasattr(org, '__reshut_deny'):
+        setattr(org, '__reshut_deny', {
+            claim_name: claim_check
+        })
+    else:
+        deny_list = cast(dict[str,Any],getattr(org, '__reshut_deny'))
+        deny_list[claim_name] = claim_check
+    return func
+    
+def require_claim(func:Callable[..., Any], claim_name:str, claim_check:Optional[Any|ClaimEvaluator] = None) -> Callable[..., Any]:
+    """
+    Adds a REQUIRED claim rule to a handler.
+
+    When all required claims are presented, then access is granted.
+    
+    :param func: The handler function.
+    :param claim_name: Claim name.
+    :param claim_check: Optional literal value that the claim must present, or a ``ClaimEvaluator`` that checks the claim is a match.
+    :return: The handler function (not wrapped.)
+    """
+    return allow_claim(func, claim_name, claim_check, True)
+
+
+__all__ = [
+    'ClaimEvaluator',
+    'allow_anonymous',
+    'allow_claim',
+    'deny_claim',
+    'require_claim'
+]

reshut/middleware/AsgiAuthorizationMiddleware.py

@@ -0,0 +1,42 @@
+# SPDX-FileCopyrightText: © 2026 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import falcon
+from falcon._typing import AsgiMiddlewareWithProcessResource
+import inspect
+from typing import Any, Mapping, Optional, cast
+from .AuthorizationEvaluator import AuthorizationEvaluator
+from .TokenEvaluator import TokenEvaluator
+
+
+class AsgiAuthorizationMiddleware(AsgiMiddlewareWithProcessResource):
+    """
+    ASGI-compatible Authorization Middleware
+
+    ---
+    Intercepts resource requests to apply Authorization logic.
+    """
+
+    __authorization_evaluator:AuthorizationEvaluator
+
+    def __init__(self, apikey_token_evaluator:Optional[TokenEvaluator], basic_token_evaluator:Optional[TokenEvaluator], bearer_token_evaluator:Optional[TokenEvaluator]) -> None:
+        self.__authorization_evaluator = AuthorizationEvaluator(apikey_token_evaluator=apikey_token_evaluator, basic_token_evaluator=basic_token_evaluator, bearer_token_evaluator=bearer_token_evaluator)
+
+    async def process_resource(self, req:falcon.Request, resp:falcon.Response, resource:object, params: Mapping[str, Any]) -> None:
+        """
+        Intercept for ``process_resource`` that evaluates authorization data in the request against authorization requirements of the resource handler.
+        """
+        handler_name = f'on_{req.method.lower()}'
+        handler = getattr(resource, handler_name, None)
+        if handler is None:
+            return
+        handler = inspect.unwrap(cast(Any, handler))
+        if getattr(handler, '__reshut_noauth', False):
+            # access granted
+            return
+        self.__authorization_evaluator.evaluate(req, handler)
+
+
+__all__ = [
+    'AsgiAuthorizationMiddleware'
+]

reshut/middleware/AuthorizationEvaluator.py

@@ -0,0 +1,80 @@
+# SPDX-FileCopyrightText: © 2026 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import falcon
+from typing import Any, Optional, cast
+from ..authorization import ClaimEvaluator
+from .TokenEvaluator import TokenEvaluator
+
+
+class AuthorizationEvaluator:
+    """
+    Evaluates the authorization data in a request against the authorization requirements of a resource handler.
+    """
+
+    __apikey_token_evaluator:Optional[TokenEvaluator]
+    __basic_token_evaluator:Optional[TokenEvaluator]
+    __bearer_token_evaluator:Optional[TokenEvaluator]
+
+    def __init__(
+            self,
+            apikey_token_evaluator:Optional[TokenEvaluator],
+            basic_token_evaluator:Optional[TokenEvaluator],
+            bearer_token_evaluator:Optional[TokenEvaluator]
+        ) -> None:
+        self.__apikey_token_evaluator = apikey_token_evaluator
+        self.__basic_token_evaluator = basic_token_evaluator
+        self.__bearer_token_evaluator = bearer_token_evaluator      
+
+    def evaluate(self, req:falcon.Request, handler:Any) -> None:
+        """
+        Evaluate authorization data in ``req`` against authorization requirements of ``handler``.
+
+        :raises falcon.HTTPBadRequest: When the request has missing or invalid Authorization data.
+        :raises falcon.HTTPUnauthorized: When claim rule checks fail.
+        """
+        scheme:str|None = None
+        token:str|None = None
+        deny_claims = {} if not hasattr(handler, '__reshut_deny') else cast(dict[str,str|ClaimEvaluator], getattr(handler, '__reshut_deny'))
+        allow_claims = {} if not hasattr(handler, '__reshut_allow') else cast(dict[str,str|ClaimEvaluator], getattr(handler, '__reshut_allow'))
+        require_claims = {} if not hasattr(handler, '__reshut_require') else cast(dict[str,str|ClaimEvaluator], getattr(handler, '__reshut_require'))
+        # check for Authorization header
+        authorization = req.get_header('Authorization', False, None)
+        if authorization is not None:
+            scheme, token = authorization.split(' ', 1)
+            scheme = scheme.lower()
+        else:
+            # check for X-API-Key header
+            token = req.get_header('X-API-Key', False, None)
+            if token is not None and len(token) > 0:
+                scheme = 'apikey'
+        if scheme is None or token is None:
+            raise falcon.HTTPBadRequest(
+                title='Authorization Required',
+                description=f'Missing Authorization',
+            )
+        match scheme:
+            case 'apikey':
+                if self.__apikey_token_evaluator is not None and self.__apikey_token_evaluator.evaluate(token, deny_claims, allow_claims, require_claims):
+                    return
+            case 'basic':
+                if self.__basic_token_evaluator is not None and self.__basic_token_evaluator.evaluate(token, deny_claims, allow_claims, require_claims):
+                    return
+            case 'bearer':
+                if self.__bearer_token_evaluator is not None and self.__bearer_token_evaluator.evaluate(token, deny_claims, allow_claims, require_claims):
+                    return
+            case _:
+                raise falcon.HTTPBadRequest(
+                    title='Authorization Unsupported',
+                    description=f'Scheme "{scheme}" not supported.',
+                )
+        # reject.
+        raise falcon.HTTPUnauthorized(
+            title='Authorization Failed',
+            description='Unsuccessful',
+        )
+
+
+__all__ = [
+    'AuthorizationEvaluator'
+]

reshut/middleware/TokenEvaluator.py

@@ -0,0 +1,76 @@
+# SPDX-FileCopyrightText: © 2026 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import falcon
+from typing import cast
+from ..authorization import ClaimEvaluator
+from ..utils import Algorithm, validate
+
+
+class TokenEvaluator:
+    """
+    Evaluates a token given an Algorithm and Key.
+    """
+
+    __algorithm:Algorithm
+    __key:str
+
+    def __init__(self, algorithm:Algorithm, key:str) -> None:
+        self.__algorithm = algorithm
+        self.__key = key
+
+    def evaluate(
+            self,
+            token:str,
+            deny_claims:dict[str,str|ClaimEvaluator],
+            allow_claims:dict[str,str|ClaimEvaluator],
+            require_claims:dict[str,str|ClaimEvaluator]
+        ) -> bool:
+        """
+        Evaluate a token against the supplied claim rules.
+
+        :param token: The token to be evaluated.
+        :param deny_claims: Claim DENY rules.
+        :param allow_claims: Claim ALLOW rules.
+        :param require_claims: Claim REQUIRE rules.
+        :raises falcon.HTTPUnauthorized: When claim rule checks fail.
+        :return: A boolean indicating success or failure, on failure the calling code should raise an appopriate exception.
+        """
+        claims = validate(self.__algorithm, self.__key, token)
+        # check for denied claims (if any match, access denied)
+        for k,claim_check in deny_claims.items():
+            claim_value = claims.get(k, None)
+            if claim_value is not None and (claim_check == None or claim_value == claim_check or (callable(claim_check) and cast(ClaimEvaluator, claim_check)(claim_value))):
+                # access denied
+                raise falcon.HTTPUnauthorized(
+                    title='Authorization Denied',
+                    description='DENY'
+                )
+        # check for required claims (if any not present, access denied]
+        for k,claim_check in require_claims.items():
+            claim_value = claims.get(k, None)
+            if claim_value is None or (claim_value != claim_check and (not callable(claim_check) or not cast(ClaimEvaluator, claim_check)(claim_value))):
+                # access denied
+                raise falcon.HTTPUnauthorized(
+                    title='Authorization Missing',
+                    description='REQUIRE'
+                )
+        # check for allowed claims (if none match, access denied)
+        if len(allow_claims) > 0:
+            for k,claim_check in allow_claims.items():
+                claim_value = claims.get(k, None)
+                if claim_value is not None and (claim_value == claim_check or (callable(claim_check) and cast(ClaimEvaluator, claim_check)(claim_value))):
+                    # access granted
+                    return True
+            # access denied
+            raise falcon.HTTPUnauthorized(
+                title='Authorization Disallowed',
+                description='ALLOW'
+            )
+        # access granted
+        return True
+
+
+__all__ = [
+    'TokenEvaluator'
+]

reshut/middleware/WsgiAuthorizationMiddleware.py

@@ -0,0 +1,42 @@
+# SPDX-FileCopyrightText: © 2026 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import falcon
+from falcon._typing import WsgiMiddlewareWithProcessResource
+import inspect
+from typing import Any, Mapping, Optional, cast
+from .AuthorizationEvaluator import AuthorizationEvaluator
+from .TokenEvaluator import TokenEvaluator
+
+
+class WsgiAuthorizationMiddleware(WsgiMiddlewareWithProcessResource):
+    """
+    WSGI-compatible Authorization Middleware
+
+    ---
+    Intercepts resource requests to apply Authorization logic.
+    """
+
+    __authorization_evaluator:AuthorizationEvaluator
+
+    def __init__(self, apikey_token_evaluator:Optional[TokenEvaluator], basic_token_evaluator:Optional[TokenEvaluator], bearer_token_evaluator:Optional[TokenEvaluator]) -> None:
+        self.__authorization_evaluator = AuthorizationEvaluator(apikey_token_evaluator=apikey_token_evaluator, basic_token_evaluator=basic_token_evaluator, bearer_token_evaluator=bearer_token_evaluator)
+
+    def process_resource(self, req:falcon.Request, resp:falcon.Response, resource:object, params: Mapping[str, Any]) -> None:
+        """
+        Intercept for ``process_resource`` that evaluates authorization data in the request against authorization requirements of the resource handler.
+        """
+        handler_name = f'on_{req.method.lower()}'
+        handler = getattr(resource, handler_name, None)
+        if handler is None:
+            return
+        handler = inspect.unwrap(cast(Any, handler))
+        if getattr(handler, '__reshut_noauth', False):
+            # access granted
+            return
+        self.__authorization_evaluator.evaluate(req, handler)
+
+
+__all__ = [
+    'WsgiAuthorizationMiddleware'
+]

reshut/middleware/__init__.py

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: © 2026 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from .AsgiAuthorizationMiddleware import AsgiAuthorizationMiddleware
+from .AuthorizationEvaluator import AuthorizationEvaluator
+from .TokenEvaluator import TokenEvaluator
+from .WsgiAuthorizationMiddleware import WsgiAuthorizationMiddleware
+
+
+__all__ = [
+    'AsgiAuthorizationMiddleware',
+    'AuthorizationEvaluator',
+    'TokenEvaluator',
+    'WsgiAuthorizationMiddleware'
+]

reshut/utils.py

@@ -0,0 +1,172 @@
+# SPDX-FileCopyrightText: © 2026 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import base64
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ec, ed25519, ed448, rsa
+from enum import StrEnum, unique
+import secrets
+import jwt
+from typing import Any, Optional
+
+
+@unique
+class Algorithm(StrEnum):
+    """
+    Enumeration of Algorithms that can be used for tokenizing claims.
+    """
+    HS256 = 'HS256'
+    """HMAC (256-bit, symmetric, fastest)"""
+    HS384 = 'HS384'
+    """HMAC (384-bit, symmetric, fastest)"""
+    HS512 = 'HS512'
+    """HMAC (512-bit, symmetric, fastest)"""
+    RS256 = 'RS256'
+    """RSA (256-bit, asymmetric, slow)"""
+    RS384 = 'RS384'
+    """RSA (384-bit, asymmetric, slow)"""
+    RS512 = 'RS512'
+    """RSA (512-bit, asymmetric, slow)"""
+    ES256 = 'ES256'
+    """Elliptic-curve (256-bit, asymmetric, fast)"""
+    ES384 = 'ES384'
+    """Elliptic-curve (384-bit, asymmetric, fast)"""
+    ES512 = 'ES512'
+    """Elliptic-curve (512-bit, asymmetric, fast)"""
+    ED25519 = 'ED25519'
+    """Edwards-curve (256-bit, asymmetric, faster)"""
+    ED448 = 'ED448'
+    """Edwards-curve (448-bit, asymmetric, faster)"""
+    def __str__(self) -> str:
+        return self.value    
+
+def keygen(algorithm:Algorithm, key_size:Optional[int] = None) -> tuple[str,str|None]:
+    """
+    Generates a key (or keypair) for the specified algorithm.
+
+    :param algorithm: The algorithm to use.
+    :param key_size: If provided, overrides the size of the generated key(s), in bits, if supported by the algorithm. Typically you would not do this.
+    :raises NotImplementedError: Raised when an unsupported algorithm is specified.
+    :return: A tuple containing the key(s) that were generated. When returning a keypair the first value is the private key, the second value is the public key.
+    """        
+    match algorithm:
+        case Algorithm.HS256 | Algorithm.HS384 | Algorithm.HS512:
+            if key_size is None:
+                match algorithm:
+                    case Algorithm.HS256:
+                        key_size = 256
+                    case Algorithm.HS384:
+                        key_size = 384
+                    case Algorithm.HS512:
+                        key_size = 512
+            return (base64.b64encode(secrets.token_bytes(key_size)).decode('ascii'), None)
+        case Algorithm.RS256 | Algorithm.RS384 | Algorithm.RS512:
+            if key_size is None:
+                match algorithm:
+                    case Algorithm.RS256:
+                        key_size = 2048
+                    case Algorithm.RS384:
+                        key_size = 3072
+                    case Algorithm.RS512:
+                        key_size = 4096
+            rsa_obj = rsa.generate_private_key(
+                public_exponent=65537,
+                key_size=key_size
+            )
+            prikey_pem = rsa_obj.private_bytes(
+                encoding=serialization.Encoding.PEM,
+                format=serialization.PrivateFormat.TraditionalOpenSSL,
+                encryption_algorithm=serialization.NoEncryption()
+            ).decode('utf-8')
+            pubkey_pem = rsa_obj.public_key().public_bytes(
+                encoding=serialization.Encoding.PEM,
+                format=serialization.PublicFormat.SubjectPublicKeyInfo
+            ).decode('utf-8')
+            return (prikey_pem, pubkey_pem)
+        case Algorithm.ES256 | Algorithm.ES384 | Algorithm.ES512:
+            curve:ec.EllipticCurve
+            match algorithm:
+                case Algorithm.ES256:
+                    curve = ec.SECP256R1()
+                case Algorithm.ES384:
+                    curve = ec.SECP384R1()
+                case Algorithm.ES512:
+                    curve = ec.SECP521R1()
+            ec_obj = ec.generate_private_key(curve)
+            prikey_pem = ec_obj.private_bytes(
+                encoding=serialization.Encoding.PEM,
+                format=serialization.PrivateFormat.PKCS8,
+                encryption_algorithm=serialization.NoEncryption()
+            ).decode('utf-8')
+            pubkey_pem = ec_obj.public_key().public_bytes(
+                encoding=serialization.Encoding.PEM,
+                format=serialization.PublicFormat.SubjectPublicKeyInfo
+            ).decode('utf-8')
+            return (prikey_pem, pubkey_pem)
+        case Algorithm.ED25519 | Algorithm.ED448:
+            eddsa_obj = (ed25519.Ed25519PrivateKey if algorithm == Algorithm.ED25519 else ed448.Ed448PrivateKey).generate()
+            prikey_pem = eddsa_obj.private_bytes(
+                encoding=serialization.Encoding.PEM,
+                format=serialization.PrivateFormat.PKCS8,
+                encryption_algorithm=serialization.NoEncryption(),
+            ).decode('utf-8')
+            pubkey_pem = eddsa_obj.public_key().public_bytes(
+                encoding=serialization.Encoding.PEM,
+                format=serialization.PublicFormat.SubjectPublicKeyInfo,
+            ).decode('utf-8')
+            return (prikey_pem, pubkey_pem)
+        case _:
+            raise NotImplementedError(f'Unsupported Algorithm "{algorithm}"')
+
+def tokenize(algorithm:Algorithm, private_key:str, claims:dict[str,Any], *, audience:Optional[str|list[str]] = None, issuer:Optional[str] = None) -> str:
+    """
+    Tokenize the provided claims, optionally injecting ``aud`` and ``iss`` claims into the claims before tokenizing.
+
+    :param algorithm: The algorithm to use when signing the token.
+    :param private_key:  The private key (or secret) used for signing.
+    :param claims: The claims to be tokenized.
+    :param audience: An optional value to be used as the ``aud`` claim.
+    :param issuer: An optional value to be used as the ``iss`` claim.
+    :return: The claims tokenized as a "compact‑serialization" JWT.
+    :raises Exception: If there is an error creating a token.
+    """    
+    try:
+        if audience is not None:
+            claims |= { 'aud': audience }
+        if issuer is not None:
+            claims |= { 'iss': issuer }
+        match algorithm:
+            case Algorithm.ED25519 | Algorithm.ED448:
+                return jwt.encode(claims, private_key, 'EdDSA')
+            case Algorithm.HS256 | Algorithm.HS384 | Algorithm.HS512:
+                return jwt.encode(claims, base64.b64decode(private_key), algorithm.value)
+            case _:
+                return jwt.encode(claims, private_key, algorithm.value)
+    except Exception as ex:
+        raise Exception()
+
+
+def validate(algorithm:Algorithm, public_key:str, token:str, *, audience:Optional[str|list[str]] = None, issuer:Optional[str] = None) -> dict[str, Any]:
+    """
+    Verify a token and return the contained claims.
+
+    If ``audience`` or ``issuer`` are provided `validate(...)` also checks the ``aud`` and ``iss`` claims.
+
+    :param algorithm: The algorithm that was used to sign the token.
+    :param public_key: The public key (or secret) used for verification.
+    :param token:     The compact‑serialization JWT string to be validated.
+    :param audience:  Expected ``aud`` claim. Omit to skip validating ``aud`` claim.
+    :param issuer:    Expected ``iss`` claim. Omit to skip validating ``iss`` claim.
+    :return:          The decoded claims (as a ``dict``).
+    :raises Exception: If the token is invalid, expired, or claims do not match.
+    """
+    try:
+        match algorithm:
+            case Algorithm.ED25519 | Algorithm.ED448:
+                return jwt.decode(token, public_key, algorithms=['EdDSA'], audience=audience, issuer=issuer, options={"verify_aud": audience is not None})
+            case Algorithm.HS256 | Algorithm.HS384 | Algorithm.HS512:
+                return jwt.decode(token, base64.b64decode(public_key), algorithms=[algorithm.value], audience=audience, issuer=issuer, options={"verify_aud": audience is not None})
+            case _:
+                return jwt.decode(token, public_key, algorithms=[algorithm.value], audience=audience, issuer=issuer)
+    except Exception as ex:
+        raise Exception()

reshut-0.0.3.dist-info/METADATA

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: reshut
+Version: 0.0.3
+Summary: ..an authorization library for Falcon.
+Author-email: Shaun Wilson <mrshaunwilson@msn.com>
+License-Expression: MIT
+Keywords: falcon,auth,bearer,apikey,hmac,rsa,ed25519,ed448
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=48
+Requires-Dist: falcon<5,>=4.2
+Requires-Dist: pyjwt<3.0.0,>=2.12.1
+Provides-Extra: dev
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: lxml-stubs==0.5.1; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: punit<2.0.0,>=1.3.7; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+
+[![reshut on PyPI](https://img.shields.io/pypi/v/reshut.svg)](https://pypi.org/project/reshut/) [![reshut on readthedocs](https://readthedocs.org/projects/reshut/badge/?version=latest)](https://reshut.readthedocs.io)
+
+**reshut** (רשות) is a decorative auth library for [Falcon](https://falconframework.org/).
+
+This README is only a high-level introduction to **reshut**. For more detailed documentation, please view the official docs at [https://reshut.readthedocs.io](https://reshut.readthedocs.io).
+
+## Installation
+
+You can install `reshut` from [PyPI](https://pypi.org/project/reshut/) through usual means, such as `pip`:
+
+```bash
+   pip install reshut
+```
+
+## Usage
+
+To use `reshut` two things must be done; first you must add an authorization middleware, and second you must apply one or more authorization decorators to a request handler method. Consider the following example:
+
+```python
+
+    import falcon
+    from reshut import middleware, utils
+    from .api.v3.FakeApi import FakeApi
+
+    # you create a falcon app
+    app = asgi.App()
+    # you register the middleware, which applies Authorization checks to ALL requests
+    symmetric_key = utils.keygen(Algorithm.HS256)
+    asymmetric_key = utils.keygen(Algorithm.ED448)
+    app.add_middleware(middleware.AsgiAuthorizationMiddleware(
+        apikey_evaluater=TokenEvaluator(Algorithm.HS256, key),
+        bearer_evaluater=TokenEvaluator(Algorithm.ED448, key)
+    ))
+    # you add some routes to your app
+    app.add_route('/api/v3/fakes', api.v3.FakeApi())
+    app.add_route('/api/v3/fakes/{id:int}', api.v3.FakeApi())
+```
+
+Elsewhere in your project, you defined `FakeApi` and decorated at least one handler to customize Authorization:
+
+```python
+
+    import falcon
+    from reshut.authorization import allow_anonymous, allow_claim, deny_claim, require_claim
+
+    class FakeApi:
+
+        def initialize(self) -> None:
+            pass
+
+        # access granted to any caller:
+        @allow_anonymous
+        async def on_delete(self, id:str) -> None:
+            pass
+
+        # access denied to callers with `fake_restricted==yes`:
+        @deny_claim('fake_restricted', 'yes')
+        # access granted to callers having either `fake_reader` OR `fake_writer`:
+        @allow_claim('fake_reader') 
+        @allow_claim('fake_writer')
+        async def on_get(self, id:str) -> None:
+            pass
+
+        # access granted to callers having `roles` claim, where one
+        # of the roles is "ADMIN", performed via `ClaimEvaluator` callback:
+        @allow_claim('roles', lambda roles: 'ADMIN' in roles)
+        # access granted to callers having `readonly_user` with a `False` value:
+        @allow_claim('readonly_user', False)
+        async def on_put(self, id:str) -> None:
+            pass
+
+        # access granted to callers having BOTH `department_id` of 123, 234, or 345
+        # and-also having `can_create==True`:
+        @require_claim('department_id', lambda x: x in [123,234,345])
+        @require_claim('can_create', True)
+        async def on_post(self, id:str) -> None:
+            pass
+```
+
+In the above example:
+
+`@allow_anonymous` will grant access to all callers, authenticated or not.
+
+`@allow_claim` specifies which claims will grant access, at least one of them must be satisfied by the request.
+
+`@deny_claim` specifies which claims will deny access.
+
+`@require_claim` specifies which claims are required for "access granted", ALL specified claims must be satisfied by the request or access is denied.
+
+All authorization decorators optionally allow matching a specific literal value or a Claim Evaluator function.  Claim Evaluator functions are useful for checking complex claim types like dates, dicts, lists, etc while literal values are useful for checking for well-known/individual values.
+
+## Generating Keys, Tokenizing Claims, and Validating Tokens
+
+If you need to generate keys there is a CLI tool `reshut-keygen` you can use:
+
+```bash
+# these generate PRIVATE SECRETS only to be used
+# by you or your organization. they are NOT to be
+# shared with a third party.
+
+# generate an hs256 secret, output ios written
+# to a "my_secret.b64" file
+reshut-keygen --type RS256 --output my_secret
+
+# generate an rs256 keypair, outputs go to
+# separate PEM files named "my_rs256_public.pem"
+# and "my_rs256_private.pem"
+reshut-keygen --type RS256 --output my_rs256
+
+# the --output arg may specify a path, the last
+# part of the path is always taken as a filename base.
+
+# if you omit --output a default is derived from
+# the --type arg, ie "hs256.b64", "rs256_public.pem",
+# and "rs256_private.pem" for the examples above.
+```
+
+There is also a `reshut-tokenize` tool you can use to tokenize claims:
+
+```bash
+    # this generates a SHARED TOKEN meant to be provided
+    # to a third party such as developers, testers,
+    # or business partners/integrators for authorization.
+
+    # tokenize claims
+    reshut-tokenize --type RS256 --key my_secret.b64 --claims '{"foo":"bar"}' --output shared_token.b64
+```
+
+Lastly, there is a `reshut-validate` tool you can use to validate tokens:
+
+```bash
+    reshut-tokenize --type RS256 --key my_secret.b64 --claims '{"foo":"bar"}' --output shared_token.b64
+```
+
+These tools are written using the `reshut.utils` namespace, you can use the utils namespace within your own code to dynamically allocate keys and tokens as you see fit for your solution (instead of dropping to a shell for the same result).
+
+For example, here is a snippet demonstrating the generation of an ed448 keypair and-also an ed448 token valid for that keypair:
+
+```python
+
+from reshut.utils import Algorithm, keygen, tokenize, validate
+
+# on the server/etc, generate keys
+ed448_prikey, ed448_pubkey = keygen(Algorithm.ED448)
+print(ed448_prikey)
+print(ed448_pubkey)
+
+# on the server/etc, issue "secure" claims (claims the recipient can see/verify, but cannot modify)
+token = tokenize(Algorithm.ED448, ed448_prikey, {
+    sub: 'Subject',
+    iss: 'Issuer',
+    exp: datetime.now()+timedelta(days=90)
+})
+print(token)
+
+claims = validate(Algorithm.ED448, ed448_pubkey, token)
+print(claims)
+
+# individual claims can then be verified.  these examples are only really useful
+# if you are automating key issuance, token issuance, are a third-party that
+# needs to generate a complex/symmetric token on-demand, or are implementing
+# a custom token validator.
+```
+
+## Contact
+
+You can reach me on [Discord](https://discordapp.com/users/307684202080501761) or [open an Issue on Github](https://github.com/wilson0x4d/reshut/issues/new/choose).

reshut-0.0.3.dist-info/RECORD

@@ -0,0 +1,15 @@
+reshut/__init__.py,sha256=H_24D1xLKZtGBOBP2QTTO7ag-qW8tsqGsUEZyMTUoko,222
+reshut/__main__.py,sha256=Avsq2EutIxoiZpTEJbj27ZeooLPN9ZxxPoBdKm2JjUc,4362
+reshut/authorization.py,sha256=O5RyKnXruYiXGGLtIjbV4GQFeb4pDeqO3mhtC9DzUu0,3163
+reshut/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+reshut/utils.py,sha256=P__BWcljtefqyAo_RdwgDK33ydAtFIgB2J348CpkxQA,8019
+reshut/middleware/AsgiAuthorizationMiddleware.py,sha256=4EevcVqY4CfzeaJYMYh98NjmrmRcQwfa59j5qvrRQ70,1690
+reshut/middleware/AuthorizationEvaluator.py,sha256=_mVR03-Ii42FWy8t4-xOvLs4uH12fDGRbKPirlrBhNI,3514
+reshut/middleware/TokenEvaluator.py,sha256=obQWU5wbYkOVGmLTOa9x8gj2ac5n-Rpoc19LrFotx0o,2953
+reshut/middleware/WsgiAuthorizationMiddleware.py,sha256=e8elEomycMSXmyqGY4FUe_lSoM7zft5c3Zcaw1LZnPY,1684
+reshut/middleware/__init__.py,sha256=RR2tHP09wPAmTnOUeLm4TbnDTQmXpCkZPlZIWKFe0uM,456
+reshut-0.0.3.dist-info/licenses/LICENSE,sha256=WDHBjw5FnacUEgi2Zf5fbjqqMMUM6Sw4DOHaIrFoewY,1058
+reshut-0.0.3.dist-info/METADATA,sha256=zzYQCOFYrYjfPj3Xr2dBOfrxC5J1AVlSzTIiLzNpQ34,7294
+reshut-0.0.3.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+reshut-0.0.3.dist-info/top_level.txt,sha256=RxpGNEH0IRWjL8NF0oLi3S7bEcubozcQoBW5hP3rlMA,7
+reshut-0.0.3.dist-info/RECORD,,

reshut-0.0.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

reshut-0.0.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+© 2026 Shaun Wilson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

reshut-0.0.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+reshut