[Feat/documentation] docs and refactoring for sd_jwt, storage, tools,…

… trust and x509 (#207)

* feat: added policy apply on metadata

* test: added intial tests for TrustEvaluationHelper

* fix: fixed validation issues

* feat: implemented method add_trust_attestation_metadata

* test: added test for add_trust_attestation_metadata

* fix: added metadata association by metadata_type field

* fix: minor fix to test for add_trust_attestation_metadata's data type

* chore: renamed test file

* chore: Removed comment

* fix: fixed x509 verification exception handling

* chore: fix typo

* fix: merged federation and metadata policy implementation

* test: adapted tests

* feat: added final_metadata property

* feat: added chain discovery plus refactoring

* docs: documented file class and functions

* fix: fixed trust_anchor_entity_conf handling

* docs: documented trust_chain_builder.py

* fix: moved implementation of get_http_url in utils.py

* fix: fixed response handling

* docs: documented file class and function plus refactoring

* docs: documented file __init__.py

* docs: added docs for http_client.py

* docs: documented the content of __init__.py

* docs: documented contento of __init__.py

* fix: method name refactoring

* fix: added exception

* fix: refactored method find_jwk

* docs: fixed documentation

* fix: refactoring

* docs: documented content of utils.py

* docs: documented __init__.py content

* fix: Resolved todo (what if the credential is not a JWT?)

* feat: implemented is_jwe_format and is_jws_format

* test: amplied test

* fix: refactored code

* feat: resolved todo (detect if it is encrypted otherwise)

* fix: code refactoring

* docs: documented content of direct_post_response.py

* fix: amplied error messages

* feat: resolved todo (automatic detection of the credential)

* docs: amplied the documentation

* fix: refactored code

* fix: added dependency

* docs: documented content of vp_sd_jwt.py

* fix: refactored code

* docs: documented content of vp.py

* fix: refactoring for better redability

* fix: redability fix

* feat: added methods for handling credential's JWKs

* fix: fixed signatures

* test: fixed test

* docs: documented the content of backend.py

* docs: documented code of dpop.py

* feat: created class BaseHTTPErrorHandler

* feat: created class BaseLogger

* chore: removed unused implementation

* fix: code refactoring

* docs: added doc for _serialize_error

* docs: documented HTTPError and EmptyHTTPError

* docs: fixed doc

* docs: documented content of html_template.py

* docs: documented content of response.py

* docs: documented content of trust.py

* fix: fixed signature

* fix: fixed message passing

* docs: documented content of __init__.py

* feat: added specialized classes for JWK

* feat: added error type

* chore: moved file base_logger.py

* chore: fixed import

* chore: fixed import

* feat: added BaseDB class and it's documentation

* docs: documented content of base_cache.py

* feat: added inheritance with BaseDB

* feat: added inheritance of BaseDB

* docs: documented content of base_storage.py

* feat: documentation and refactoring

* feat: documentation and refactoring

* fix: varius minor fixs

* docs: documented content of mobile.py

* docs: documented content of schema_utils.py

* docs: documented content of utils.py

* docs: documented content of trust_anchors.py

* docs: documented content of trust_chain.py

* docs: documented content of verify.py

* docs: fixed docs

* fix: fixed functions name

---------

Co-authored-by: Giuseppe De Marco <[email protected]>

pyeudiw/jwk/__init__.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import json
 from typing import Union
 
@@ -6,14 +8,14 @@
 from cryptojwt.jwk.jwk import key_from_jwk_dict
 from cryptojwt.jwk.rsa import new_rsa_key
 
-from .exceptions import InvalidKid, KidNotFoundError
+from .exceptions import InvalidKid, KidNotFoundError, InvalidJwk
 
 KEY_TYPES_FUNC = dict(
     EC=new_ec_key,
     RSA=new_rsa_key
 )
 
-class JWK():
+class JWK:
     """
     The class representing a JWK istance
     """
@@ -117,6 +119,34 @@ def as_dict(self) -> dict:
     def __repr__(self):
         # private part!
         return self.as_json()
+
+class RSAJWK(JWK):
+    def __init__(self, key: dict | None = None, hash_func: str = "SHA-256") -> None:
+        super().__init__(key, "RSA", hash_func, None)
+
+class ECJWK(JWK):
+    def __init__(self, key: dict | None = None, hash_func: str = "SHA-256", ec_crv: str = "P-256") -> None:
+        super().__init__(key, "EC", hash_func, ec_crv)
+
+def jwk_form_dict(key: dict, hash_func: str = "SHA-256") -> RSAJWK | ECJWK:
+    """
+    Returns a JWK instance from a dict.
+
+    :param key: a dict that represents the key.
+    :type key: dict
+
+    :returns: a JWK instance.
+    :rtype: JWK
+    """
+    _kty = key.get('kty', None)
+
+    if _kty == None or _kty not in ['EC', 'RSA']:
+        raise InvalidJwk("Invalid JWK")
+    elif _kty == "RSA":
+        return RSAJWK(key, hash_func)
+    else:
+        ec_crv = key.get('crv', "P-256")
+        return ECJWK(key, hash_func, ec_crv)
 
 def find_jwk(kid: str, jwks: list[dict], as_dict: bool=True) -> dict | JWK:
     """

pyeudiw/jwk/exceptions.py

@@ -10,3 +10,6 @@ class InvalidKid(Exception):
 
 class JwkError(Exception):
     pass
+
+class InvalidJwk(Exception):
+    pass

pyeudiw/satosa/backend.py

@@ -41,7 +41,7 @@
 
 from .exceptions import HTTPError
 from .base_http_error_handler import BaseHTTPErrorHandler
-from .base_logger import BaseLogger
+from pyeudiw.tools.base_logger import BaseLogger
 
 class OpenID4VPBackend(BackendModule, BackendTrust, BackendDPoP, BaseHTTPErrorHandler, BaseLogger):
     """
@@ -152,8 +152,8 @@ def start_auth(self, context: Context, internal_request) -> Response:
 
     def pre_request_endpoint(self, context: Context, internal_request, **kwargs) -> Response:
         """
-        This endpoint is called by the frontend before calling the request endpoint.
-        It initializes the session and returns the request_uri to be used by the frontend.
+        This endpoint is called by the User-Agent/Wallet Instance before calling the request endpoint.
+        It initializes the session and returns the request_uri to be used by the User-Agent/Wallet Instance.
 
         :type context: the context of current request
         :param context: the request context
@@ -213,18 +213,18 @@ def pre_request_endpoint(self, context: Context, internal_request, **kwargs) ->
         )
         return Response(result, content="text/html; charset=utf8", status="200")
 
-    def redirect_endpoint(self, context: Context, *args: tuple) -> Redirect | JsonResponse:
+    def request_endpoint(self, context: Context, *args: tuple) -> Redirect | JsonResponse:
         """
-        This endpoint is called by the frontend after the user has been authenticated.
+        This endpoint is called by the User-Agent/Wallet Instance to retrieve the signed signed Request Object.
 
         :type context: the context of current request
         :param context: the request context
 
-        :return: a redirect to the frontend, if is in same device flow, or a json response if is in cross device flow.
+        :return: a redirect to the User-Agent/Wallet Instance, if is in same device flow, or a json response if is in cross device flow.
         :rtype: Redirect | JsonResponse
         """
 
-        self._log_function_debug("redirect_endpoint", context, "args", args)
+        self._log_function_debug("request_endpoint", context, "args", args)
 
         if context.request_method.lower() != 'post':
             # raise BadRequestError("HTTP Method not supported")
@@ -391,9 +391,9 @@ def redirect_endpoint(self, context: Context, *args: tuple) -> Redirect | JsonRe
                 status="200"
             )
 
-    def request_endpoint(self, context: Context, *args) -> JsonResponse:
+    def redirect_endpoint(self, context: Context, *args) -> JsonResponse:
         """
-        This endpoint is called by the frontend to retrieve the signed signed Request Object.
+        This endpoint is called by the User-Agent/Wallet Instance after the user has been authenticated.
 
         :type context: the context of current request
         :param context: the request context
@@ -404,7 +404,7 @@ def request_endpoint(self, context: Context, *args) -> JsonResponse:
         :rtype: JsonResponse
         """
 
-        self._log_function_debug("request_endpoint", context, "args", args)
+        self._log_function_debug("redirect_endpoint", context, "args", args)
 
         # check DPOP for WIA if any
         try:
@@ -479,7 +479,7 @@ def request_endpoint(self, context: Context, *args) -> JsonResponse:
 
     def get_response_endpoint(self, context: Context) -> Response:
         """
-        This endpoint is called by the frontend to retrieve the response of the authentication.
+        This endpoint is called by the User-Agent/Wallet Instance to retrieve the response of the authentication.
         
         :param context: the request context
         :type context: satosa.context.Context
@@ -529,7 +529,7 @@ def get_response_endpoint(self, context: Context) -> Response:
 
     def status_endpoint(self, context: Context) -> JsonResponse:
         """
-        This endpoint is called by the frontend the url to the response endpoint to finalize the process.
+        This endpoint is called by the User-Agent/Wallet Instance the url to the response endpoint to finalize the process.
 
         :param context: the request context
         :type context: satosa.context.Context

pyeudiw/satosa/base_http_error_handler.py

@@ -1,5 +1,5 @@
 from satosa.context import Context
-from .base_logger import BaseLogger
+from pyeudiw.tools.base_logger import BaseLogger
 from .exceptions import EmptyHTTPError
 from pyeudiw.satosa.response import JsonResponse
 

pyeudiw/satosa/dpop.py

@@ -9,7 +9,7 @@
 from satosa.context import Context
 from pydantic import ValidationError
 
-from .base_logger import BaseLogger
+from pyeudiw.tools.base_logger import BaseLogger
 from .base_http_error_handler import BaseHTTPErrorHandler
 
 class BackendDPoP(BaseHTTPErrorHandler, BaseLogger):

pyeudiw/satosa/trust.py

@@ -14,7 +14,7 @@
 from pyeudiw.trust import TrustEvaluationHelper
 from pyeudiw.trust.trust_anchors import update_trust_anchors_ecs
 
-from .base_logger import BaseLogger
+from pyeudiw.tools.base_logger import BaseLogger
 
 class BackendTrust(BaseLogger):
     """