protegrity-ai-developer-python 1.2.1__py3-none-any.whl

appython/utils/input_preprocessor.py

@@ -0,0 +1,325 @@
+"""
+This module provides the InputPreprocessor class, which is responsible for validating and processing
+input parameters for data protection operations such as PROTECT, UNPROTECT, and REPROTECT.
+It ensures that the input data is correctly formatted, handles character sets, and prepares the
+parameters for further processing.
+"""
+
+from appython.utils.constants import (
+    ARGS_PROTECT as args_protect,
+    OP_TYPE as op_type,
+    ARGS_UNPROTECT as args_unprotect,
+    ARGS_REPROTECT as args_reprotect,
+    DATATYPES as datatypes,
+    ErrorMessage,
+    Charset,
+)
+from appython.utils.codec_helper import (
+    convert_b64_bytes_b64_string,
+    decode_bytes,
+    encode_to_base64_string,
+)
+
+
+def validate_charset(kwargs, response_type):
+    """
+    Validates the use of the 'charset' keyword argument based on the expected response type.
+
+    This function ensures that the 'charset' parameter is only used when the response type is 'bytes'.
+    If 'charset' is provided in the kwargs and the response type is not bytes, an exception is raised.
+
+    Parameters:
+        kwargs (dict): Dictionary of keyword arguments that may include 'charset'.
+        response_type (type): The expected type of the response (e.g., bytes, str).
+
+    Raises:
+        Exception: If 'charset' is specified in kwargs but the response_type is not bytes.
+    """
+
+    if "charset" in kwargs and response_type != bytes:
+        raise Exception(ErrorMessage.INVALID_CHARSET_TYPE.value)
+    else:
+        if "charset" in kwargs and response_type == bytes:
+            try:
+                if kwargs["charset"].value not in [
+                    Charset.UTF8.value,
+                    Charset.UTF16LE.value,
+                    Charset.UTF16BE.value,
+                ]:
+                    raise Exception(ErrorMessage.UNSUPPORTED_CHARSET.value)
+            except Exception:
+                raise Exception(ErrorMessage.UNSUPPORTED_CHARSET.value)
+
+
+class InputPreprocessor:
+
+    @staticmethod
+    def validate_parameters(
+        kwargs, inp_type, operation_type: str, user: str, de: str, newde: str = None
+    ) -> dict:
+        """
+        Validates and constructs the parameter dictionary for different data protection operations.
+
+        This method ensures that the required parameters for PROTECT, UNPROTECT, and REPROTECT operations
+        are present and correctly typed. It also encodes optional parameters like external IVs and tweaks
+        into base64 strings when necessary.
+
+        Parameters:
+            kwargs (dict): Additional keyword arguments specific to the operation.
+            inp_type (type): The expected response type (e.g., str, bytes).
+            operation_type (str): The type of operation to perform ('PROTECT', 'UNPROTECT', or 'REPROTECT').
+            user (str): The user identifier.
+            de (str): The data element name.
+            newde (str, optional): The new data element name (required for REPROTECT).
+
+        Returns:
+            dict: A dictionary containing validated and formatted parameters for the operation.
+
+        Raises:
+            Exception: If any required parameter is missing or of an invalid type, or if unsupported
+                        keyword arguments are provided.
+        """
+
+        argv = {
+            "parameters": {
+                "user": user,
+                "data_element": de,
+                "new_data_element": newde,
+                "response_type": inp_type,
+            }
+        }
+
+        if not isinstance(user, str):
+            raise Exception(ErrorMessage.INVALID_USER_NAME.value)
+
+        operation = op_type[operation_type]
+
+        if operation in ["PROTECT", "UNPROTECT"]:
+
+            if de is None or de == "":
+                raise Exception(ErrorMessage.DATA_ELEMENT_NONE_EMPTY.value)
+            if not isinstance(de, str):
+                raise Exception(ErrorMessage.DATA_ELEMENT_NOT_STR.value)
+
+            if "external_iv" in kwargs:
+                if not isinstance(kwargs["external_iv"], bytes):
+                    raise Exception(
+                        ErrorMessage.INVALID_KEYWORD_EXTERNAL_IV.value
+                        + f" Expected: bytes, Actual: {type(kwargs['external_iv'])}"
+                    )
+                argv["parameters"]["external_iv"] = convert_b64_bytes_b64_string(
+                    kwargs["external_iv"]
+                )
+
+            if "external_tweak" in kwargs:
+                if not isinstance(kwargs["external_tweak"], bytes):
+                    raise Exception(
+                        ErrorMessage.INVALID_KEYWORD_EXTERNAL_TWEAK.value
+                        + f" Expected: bytes, Actual: {type(kwargs['external_tweak'])}"
+                    )
+                argv["parameters"]["external_tweak"] = convert_b64_bytes_b64_string(
+                    kwargs["external_tweak"]
+                )
+
+            if operation == "PROTECT":
+                if "encrypt_to" in kwargs:
+                    if kwargs["encrypt_to"] != bytes:
+                        raise Exception(
+                            ErrorMessage.INVALID_ENC_TYPE.value
+                            + f" - {kwargs['encrypt_to']}"
+                        )
+                    argv["parameters"]["response_type"] = bytes
+
+                validate_charset(kwargs, argv["parameters"]["response_type"])
+
+                for key in kwargs:
+                    if key not in args_protect:
+                        raise Exception(
+                            f"-1, Invalid Keyword Argument: '{key}'. {ErrorMessage.PROTECT_KEYWORD_EXP.value}"
+                        )
+
+            elif operation == "UNPROTECT":
+                if "decrypt_to" in kwargs:
+                    if kwargs["decrypt_to"] not in datatypes:
+                        raise Exception(
+                            ErrorMessage.INVALID_DEC_TYPE.value
+                            + f" - {kwargs['decrypt_to']}"
+                        )
+                    argv["parameters"]["response_type"] = kwargs["decrypt_to"]
+
+                validate_charset(kwargs, argv["parameters"]["response_type"])
+
+                for key in kwargs:
+                    if key not in args_unprotect:
+                        raise Exception(
+                            f"-1, Invalid Keyword Argument: '{key}'. {ErrorMessage.UNPROTECT_KEYWORD_EXP.value}"
+                        )
+
+        elif operation == "REPROTECT":
+            if de is None or de == "":
+                raise Exception(ErrorMessage.DATA_ELEMENT_NONE_EMPTY.value)
+            if not isinstance(de, str):
+                raise Exception(ErrorMessage.DATA_ELEMENT_NOT_STR.value)
+
+            if newde is None or newde == "":
+                raise Exception(ErrorMessage.NEW_DATA_ELEMENT_NONE_EMPTY.value)
+            if not isinstance(newde, str):
+                raise Exception(ErrorMessage.NEW_DATA_ELEMENT_NOT_STR.value)
+
+            if "old_external_iv" in kwargs and "new_external_iv" in kwargs:
+                if not isinstance(kwargs["old_external_iv"], bytes):
+                    raise Exception(
+                        ErrorMessage.INVALID_KEYWORD_OLD_EXTERNAL_IV.value
+                        + f" Expected: bytes, Actual: {type(kwargs['old_external_iv'])}"
+                    )
+                argv["parameters"]["old_external_iv_str"] = (
+                    convert_b64_bytes_b64_string(kwargs["old_external_iv"])
+                )
+
+                if not isinstance(kwargs["new_external_iv"], bytes):
+                    raise Exception(
+                        ErrorMessage.INVALID_KEYWORD_NEW_EXTERNAL_IV.value
+                        + f" Expected: bytes, Actual: {type(kwargs['new_external_iv'])}"
+                    )
+                argv["parameters"]["new_external_iv"] = convert_b64_bytes_b64_string(
+                    kwargs["new_external_iv"]
+                )
+            elif "old_external_iv" in kwargs or "new_external_iv" in kwargs:
+                raise Exception(ErrorMessage.MISSING_OLD_EIV_OR_NEW_EIV.value)
+
+            if "old_external_tweak" in kwargs and "new_external_tweak" in kwargs:
+                if not isinstance(kwargs["old_external_tweak"], bytes):
+                    raise Exception(
+                        ErrorMessage.INVALID_KEYWORD_OLD_EXTERNAL_TWEAK.value
+                        + f" Expected: bytes, Actual: {type(kwargs['old_external_tweak'])}"
+                    )
+                argv["parameters"]["old_external_tweak"] = convert_b64_bytes_b64_string(
+                    kwargs["old_external_tweak"]
+                )
+
+                if not isinstance(kwargs["new_external_tweak"], bytes):
+                    raise Exception(
+                        ErrorMessage.INVALID_KEYWORD_NEW_EXTERNAL_TWEAK.value
+                        + f" Expected: bytes, Actual: {type(kwargs['new_external_tweak'])}"
+                    )
+                argv["parameters"]["new_external_tweak"] = convert_b64_bytes_b64_string(
+                    kwargs["new_external_tweak"]
+                )
+            elif "old_external_tweak" in kwargs or "new_external_tweak" in kwargs:
+                raise Exception(ErrorMessage.MISSING_OLD_TWEAK_OR_NEW_TWEAK.value)
+
+            if "encrypt_to" in kwargs:
+                if kwargs["encrypt_to"] != bytes:
+                    raise Exception(
+                        ErrorMessage.INVALID_ENC_TYPE.value
+                        + f" - {kwargs['encrypt_to']}"
+                    )
+                argv["parameters"]["response_type"] = bytes
+
+            validate_charset(kwargs, argv["parameters"]["response_type"])
+
+            for key in kwargs:
+                if key not in args_reprotect:
+                    raise Exception(
+                        f"-1, Invalid Keyword Argument: '{key}'. {ErrorMessage.REPROTECT_KEYWORD_EXP.value}"
+                    )
+
+        return argv
+
+    @staticmethod
+    def convert_input_to_string(
+        input_data, kwargs, data_element, operation_type
+    ) -> dict:
+        """
+        Converts input data into a string or base64-encoded format suitable for protection operations.
+
+        This method handles both single and bulk inputs, validates data types, and applies encoding
+        or decoding based on the data element and operation type. It also respects character set
+        preferences provided in kwargs.
+
+        Parameters:
+            input_data (Any): The input data to be processed (can be a single value or a list).
+            kwargs (dict): Additional keyword arguments, including optional charset.
+            data_element (str): The data element type (used to determine encoding behavior).
+            operation_type (str): The operation being performed ('PROTECT', 'UNPROTECT', etc.).
+
+        Returns:
+            dict: A dictionary containing the processed data, its type, original data type,
+                    charset used, and whether the input was bulk.
+
+        Raises:
+            Exception: If the input data contains unsupported or inconsistent types.
+        """
+
+        curr_input_datatype = None
+        is_bulk = False
+        input_type = None
+        charset = Charset.UTF8
+
+        if not data_element or not isinstance(data_element, str):
+            raise Exception(
+                ErrorMessage.DATA_ELEMENT_NONE_EMPTY.value
+                if not data_element
+                else ErrorMessage.DATA_ELEMENT_NOT_STR.value
+            )
+
+        is_enc = "text" in data_element or "BYTE" in data_element
+
+        # Preserve charset from kwargs if valid
+        if "charset" in kwargs and isinstance(kwargs["charset"], Charset):
+            charset = kwargs["charset"]
+
+        if isinstance(input_data, tuple):
+            input_type = type(input_data)
+            input_data = list(input_data)
+        elif isinstance(input_data, list):
+            input_data = input_data.copy()
+            input_type = type(input_data)
+
+        if isinstance(input_data, list):
+            is_bulk = True
+            for index, data in enumerate(input_data):
+                if data is None:
+                    continue
+                type_data = type(data)
+                if curr_input_datatype and type_data != curr_input_datatype:
+                    raise Exception(ErrorMessage.INVALID_BULK_INPUT.value)
+                if type_data in datatypes:
+                    curr_input_datatype = curr_input_datatype or type_data
+                    if datatypes[type_data] != 5:
+                        input_data[index] = (
+                            encode_to_base64_string(data)
+                            if is_enc and op_type[operation_type] == "PROTECT"
+                            else str(data)
+                        )
+                    else:
+                        input_data[index] = decode_bytes(
+                            data, charset, is_enc, operation_type
+                        )
+                else:
+                    raise Exception(f"-1, Unsupported input data type {type_data} !")
+        else:
+            type_data = type(input_data)
+            input_type = type_data
+            if input_data is not None and type_data in datatypes:
+                curr_input_datatype = type_data
+                if datatypes[type_data] != 5:
+                    input_data = (
+                        encode_to_base64_string(input_data)
+                        if is_enc and op_type[operation_type] == "PROTECT"
+                        else str(input_data)
+                    )
+                else:
+                    input_data = decode_bytes(
+                        input_data, charset, is_enc, operation_type
+                    )
+            elif input_data is not None:
+                raise Exception(f"-1, Unsupported input data type {type_data} !")
+
+        return {
+            "data": input_data,
+            "type": input_type,
+            "input_datatype": curr_input_datatype,
+            "charset": charset,
+            "is_bulk": is_bulk,
+        }

appython/utils/output_postprocessor.py

@@ -0,0 +1,99 @@
+"""
+This module provides the OutputProcessor class, which is responsible for restoring the original data types
+of protected or transformed values based on specified metadata. It supports various data types including
+strings, integers, floats, bytes with specific charsets, and dates in multiple formats.
+"""
+
+import base64
+from datetime import date, datetime
+from appython.utils.constants import (
+    Charset,
+    LOG_RETURN_CODE_UNSUPPORTED as log_return_code
+) 
+from appython.utils.codec_helper import get_str_from_b64
+
+
+class OutputProcessor:
+    @staticmethod
+    def restore_original_type(data: list, return_type: dict):
+        """
+        Restores the original data type(s) of protected or transformed values based on the specified return metadata.
+
+        This method decodes or converts each item in the input list `data` to its intended type as described in
+        the `return_type` dictionary. It supports both single and bulk inputs, and handles decoding for base64-encoded
+        strings, numeric types, byte strings with specific charsets, and date formats.
+
+        Parameters:
+            data (list): A list of values (usually strings) to be converted back to their original types.
+            return_type (dict): Metadata describing the expected output format. Keys include:
+                - "is_bulk" (bool): Whether the input is a list of values or a single value.
+                - "response_type" (type): The target Python type (e.g., str, int, float, bytes, date).
+                - "isENC" (bool): Whether the input values are base64-encoded.
+                - "charset" (Charset, optional): Character encoding to use when decoding byte strings.
+
+        Returns:
+            The decoded value(s), either as a single item or a list, depending on the `is_bulk` flag.
+
+        Raises:
+            Exception: If decoding fails or the response type is unsupported.
+        """
+        try:
+            is_bulk = return_type["is_bulk"]
+            response_type = return_type["response_type"]
+            is_enc = return_type["isENC"]
+            charset = return_type.get("charset")
+
+            def decode(item):
+                if item is None:
+                    return None
+                if response_type == str:
+                    return get_str_from_b64(item) if is_enc else item
+                elif response_type == int:
+                    return int(get_str_from_b64(item)) if is_enc else int(item)
+                elif response_type == float:
+                    return float(get_str_from_b64(item)) if is_enc else float(item)
+                elif response_type == bytes:
+                    if is_enc:
+                        return base64.b64decode(item)
+                    if charset.value == Charset.UTF8.value:
+                        return item.encode("utf-8")
+                    elif charset.value == Charset.UTF16LE.value:
+                        return item.encode("utf-16le")
+                    elif charset.value == Charset.UTF16BE.value:
+                        return item.encode("utf-16be")
+                elif response_type == date:
+                    date_formats = [
+                        "%Y-%m-%d",  # 2023-12-25
+                        "%Y/%m/%d",  # 2023/12/25
+                        "%Y/%d/%m",  # 2023/25/12
+                        "%m/%d/%Y",  # 12/25/2023
+                        "%d/%m/%Y",  # 25/12/2023
+                        "%m-%d-%Y",  # 12-25-2023
+                        "%d-%m-%Y",  # 25-12-2023
+                        "%Y%m%d",  # 20231225
+                        "%d.%m.%Y",  # 25.12.2023
+                        "%Y.%m.%d",  # 2023.12.25
+                    ]
+
+                    for fmt in date_formats:
+                        try:
+                            return datetime.strptime(item, fmt).date()
+                        except ValueError:
+                            continue
+
+                    # If no format worked, raise an error with the original item
+                    raise ValueError(
+                        f"Unable to parse date format for: '{item}'. Supported formats: {date_formats}"
+                    )
+                elif response_type == type(None):
+                    return None
+                else:
+                    raise Exception(f"26, {log_return_code[26]}")
+
+            if not is_bulk:
+                return decode(data[0])
+            else:
+                return [decode(item) for item in data]
+
+        except Exception:
+            raise Exception(f"26, {log_return_code[26]}")