openlinktoken 2.0.0__py3-none-any.whl

openlinktoken/metadata.py

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: MIT
+
+import hashlib
+import sys
+from typing import Any, Dict
+
+
+class Metadata:
+    """Handles metadata generation and management for Open Link Token."""
+
+    # Metadata keys
+    PLATFORM = "Platform"
+    PYTHON_VERSION = "PythonVersion"
+    VERSION = "Version"
+    OUTPUT_FORMAT = "OutputFormat"
+    ENCRYPTION_SECRET_HASH = "EncryptionSecretHash"
+    HASHING_SECRET_HASH = "HashingSecretHash"
+    BLANK_TOKENS_BY_RULE = "BlankTokensByRule"
+
+    # Metadata values
+    PLATFORM_PYTHON = "Python"
+    METADATA_FILE_EXTENSION = ".metadata.json"
+    SYSTEM_PYTHON_VERSION = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+
+    DEFAULT_VERSION = "2.0.0"
+
+    # Output format values
+    OUTPUT_FORMAT_JSON = "JSON"
+    OUTPUT_FORMAT_CSV = "CSV"
+    OUTPUT_FORMAT_PARQUET = "Parquet"
+
+    def __init__(self):
+        """Initialize the metadata object."""
+        self.metadata_map: Dict[str, Any] = {}
+
+    def initialize(self) -> Dict[str, Any]:
+        """
+        Initialize metadata with system information only.
+        Secret hashes must be set separately using add_hashed_secret().
+
+        Returns:
+            The initialized metadata map
+        """
+        self.metadata_map.clear()
+        self.metadata_map[self.PYTHON_VERSION] = self.SYSTEM_PYTHON_VERSION
+        self.metadata_map[self.PLATFORM] = self.PLATFORM_PYTHON
+        self.metadata_map[self.VERSION] = self.DEFAULT_VERSION
+
+        return self.metadata_map
+
+    def add_hashed_secret(self, secret_key: str, secret_to_hash: str | bytes | None) -> Dict[str, Any]:
+        """
+        Set the secret and add its hash to the metadata.
+
+        Args:
+            secret_key: The key to use for the hashed secret in metadata
+            secret_to_hash: The secret to hash
+
+        Returns:
+            The metadata map for method chaining
+        """
+        if isinstance(secret_to_hash, bytes):
+            if secret_to_hash:
+                self.metadata_map[secret_key] = self.calculate_secure_hash(secret_to_hash)
+        elif secret_to_hash and secret_to_hash.strip():
+            self.metadata_map[secret_key] = self.calculate_secure_hash(secret_to_hash)
+        return self.metadata_map
+
+    @staticmethod
+    def calculate_secure_hash(input_str: str | bytes | None) -> str | None:
+        """
+        Calculate a secure SHA-256 hash of the given input.
+        The hash is returned as a hexadecimal string, or ``None`` for empty input.
+
+        Accepts both ``str`` (encoded as UTF-8) and raw ``bytes``.
+
+        Args:
+            input_str: The input string or raw bytes to hash.
+
+        Returns:
+            The SHA-256 hash as a hexadecimal string, or ``None`` when the input is empty.
+
+        Raises:
+            HashCalculationException: If there's an error calculating the hash.
+        """
+        if not input_str:
+            return None
+
+        try:
+            hash_input = input_str if isinstance(input_str, bytes) else input_str.encode("utf-8")
+            hash_object = hashlib.sha256(hash_input)
+            hex_string = hash_object.hexdigest()
+            return hex_string
+
+        except Exception as e:
+            raise HashCalculationException("Error calculating SHA-256 hash", e)
+
+
+class HashCalculationException(Exception):
+    """Custom exception for hash calculation errors."""
+
+    def __init__(self, message: str, cause: Exception = None):
+        super().__init__(message)
+        self.cause = cause

openlinktoken/tokens/__init__.py

@@ -0,0 +1,19 @@
+"""Token definitions and generation utilities for Open Link Token."""
+
+from .base_token_definition import BaseTokenDefinition
+from .token import Token
+from .token_definition import TokenDefinition
+from .token_generation_exception import TokenGenerationException
+from .token_generator import TokenGenerator
+from .token_generator_result import TokenGeneratorResult
+from .token_registry import TokenRegistry
+
+__all__ = [
+    "Token",
+    "TokenDefinition",
+    "BaseTokenDefinition",
+    "TokenGenerator",
+    "TokenRegistry",
+    "TokenGeneratorResult",
+    "TokenGenerationException",
+]

openlinktoken/tokens/base_token_definition.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: MIT
+
+from abc import ABC, abstractmethod
+from typing import List, Set
+
+from openlinktoken.attributes.attribute_expression import AttributeExpression
+
+
+class BaseTokenDefinition(ABC):
+    """
+    A generic interface for the token definition.
+    """
+
+    @abstractmethod
+    def get_version(self) -> str:
+        """
+        Get the version of the token definition.
+
+        Returns:
+            The token definition version.
+        """
+        ...  # pragma: no cover
+
+    @abstractmethod
+    def get_token_identifiers(self) -> Set[str]:
+        """
+        Get all token identifiers. For example, a set of { T1, T2, T3, T4, T5 }.
+
+        The token identifiers are also called rule identifiers because every token is
+        generated from rule definition.
+
+        Returns:
+            A set of token identifiers.
+        """
+        ...  # pragma: no cover
+
+    @abstractmethod
+    def get_token_definition(self, token_id: str) -> List[AttributeExpression]:
+        """
+        Get the token definition for a given token identifier.
+
+        Args:
+            token_id: The token/rule identifier.
+
+        Returns:
+            A list of token/rule definition.
+        """
+        ...  # pragma: no cover

openlinktoken/tokens/definitions/t1_token.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: MIT
+
+from typing import List
+
+from openlinktoken.attributes.attribute_expression import AttributeExpression
+from openlinktoken.attributes.person.birth_date_attribute import BirthDateAttribute
+from openlinktoken.attributes.person.first_name_attribute import FirstNameAttribute
+from openlinktoken.attributes.person.last_name_attribute import LastNameAttribute
+from openlinktoken.attributes.person.sex_attribute import SexAttribute
+from openlinktoken.tokens.token import Token
+
+
+class T1Token(Token):
+    """
+    Represents the token definition for token T1.
+
+    It is a collection of attribute expressions that are concatenated together
+    to get the token signature. The token signature is as follows:
+    U(last-name)|U(first-name-1)|U(gender)|birth-date
+    """
+
+    ID = "T1"
+
+    def __init__(self):
+        """Initialize the T1 token definition."""
+        self._definition = [
+            AttributeExpression(LastNameAttribute, "T|U"),
+            AttributeExpression(FirstNameAttribute, "T|S(0,1)|U"),
+            AttributeExpression(SexAttribute, "T|U"),
+            AttributeExpression(BirthDateAttribute, "T|D"),
+        ]
+
+    def get_identifier(self) -> str:
+        """Get the unique identifier for the token."""
+        return self.ID
+
+    def get_definition(self) -> List[AttributeExpression]:
+        """Get the list of attribute expressions that define the token."""
+        return self._definition

openlinktoken/tokens/definitions/t2_token.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: MIT
+
+from typing import List
+
+from openlinktoken.attributes.attribute_expression import AttributeExpression
+from openlinktoken.attributes.person.birth_date_attribute import BirthDateAttribute
+from openlinktoken.attributes.person.first_name_attribute import FirstNameAttribute
+from openlinktoken.attributes.person.last_name_attribute import LastNameAttribute
+from openlinktoken.attributes.person.postal_code_attribute import PostalCodeAttribute
+from openlinktoken.tokens.token import Token
+
+
+class T2Token(Token):
+    """
+    Represents the token definition for token T2.
+
+    It is a collection of attribute expressions that are concatenated together
+    to get the token signature. The token signature is as follows:
+    U(last-name)|U(first-name)|birth-date|postal-code-3
+    """
+
+    ID = "T2"
+
+    def __init__(self):
+        """Initialize the T2 token definition."""
+        self._definition = [
+            AttributeExpression(LastNameAttribute, "T|U"),
+            AttributeExpression(FirstNameAttribute, "T|U"),
+            AttributeExpression(BirthDateAttribute, "T|D"),
+            AttributeExpression(PostalCodeAttribute, "T|S(0,3)|U"),
+        ]
+
+    def get_identifier(self) -> str:
+        """Get the unique identifier for the token."""
+        return self.ID
+
+    def get_definition(self) -> List[AttributeExpression]:
+        """Get the list of attribute expressions that define the token."""
+        return self._definition

openlinktoken/tokens/definitions/t3_token.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: MIT
+
+from typing import List
+
+from openlinktoken.attributes.attribute_expression import AttributeExpression
+from openlinktoken.attributes.person.birth_date_attribute import BirthDateAttribute
+from openlinktoken.attributes.person.first_name_attribute import FirstNameAttribute
+from openlinktoken.attributes.person.last_name_attribute import LastNameAttribute
+from openlinktoken.attributes.person.sex_attribute import SexAttribute
+from openlinktoken.tokens.token import Token
+
+
+class T3Token(Token):
+    """
+    Represents the token definition for token T3.
+
+    It is a collection of attribute expressions that are concatenated together
+    to get the token signature. The token signature is as follows:
+    U(last-name)|U(first-name)|U(gender)|birth-date
+    """
+
+    ID = "T3"
+
+    def __init__(self):
+        """Initialize the T3 token definition."""
+        self._definition = [
+            AttributeExpression(LastNameAttribute, "T|U"),
+            AttributeExpression(FirstNameAttribute, "T|U"),
+            AttributeExpression(SexAttribute, "T|U"),
+            AttributeExpression(BirthDateAttribute, "T|D"),
+        ]
+
+    def get_identifier(self) -> str:
+        """Get the unique identifier for the token."""
+        return self.ID
+
+    def get_definition(self) -> List[AttributeExpression]:
+        """Get the list of attribute expressions that define the token."""
+        return self._definition

openlinktoken/tokens/definitions/t4_token.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: MIT
+
+from typing import List
+
+from openlinktoken.attributes.attribute_expression import AttributeExpression
+from openlinktoken.attributes.person.birth_date_attribute import BirthDateAttribute
+from openlinktoken.attributes.person.sex_attribute import SexAttribute
+from openlinktoken.attributes.person.social_security_number_attribute import SocialSecurityNumberAttribute
+from openlinktoken.tokens.token import Token
+
+
+class T4Token(Token):
+    """
+    Represents the token definition for token T4.
+
+    It is a collection of attribute expressions that are concatenated together
+    to get the token signature. The token signature is as follows:
+    social-security-number|U(gender)|birth-date
+    """
+
+    ID = "T4"
+
+    def __init__(self):
+        """Initialize the T4 token definition."""
+        self._definition = [
+            AttributeExpression(SocialSecurityNumberAttribute, "T|M(\\d+)"),
+            AttributeExpression(SexAttribute, "T|U"),
+            AttributeExpression(BirthDateAttribute, "T|D"),
+        ]
+
+    def get_identifier(self) -> str:
+        """Get the unique identifier for the token."""
+        return self.ID
+
+    def get_definition(self) -> List[AttributeExpression]:
+        """Get the list of attribute expressions that define the token."""
+        return self._definition

openlinktoken/tokens/definitions/t5_token.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: MIT
+
+from typing import List
+
+from openlinktoken.attributes.attribute_expression import AttributeExpression
+from openlinktoken.attributes.person.first_name_attribute import FirstNameAttribute
+from openlinktoken.attributes.person.last_name_attribute import LastNameAttribute
+from openlinktoken.attributes.person.sex_attribute import SexAttribute
+from openlinktoken.tokens.token import Token
+
+
+class T5Token(Token):
+    """
+    Represents the token definition for token T5.
+
+    It is a collection of attribute expressions that are concatenated together
+    to get the token signature. The token signature is as follows:
+    U(last-name)|U(first-name-3)|U(gender)
+    """
+
+    ID = "T5"
+
+    def __init__(self):
+        """Initialize the T5 token definition."""
+        self._definition = [
+            AttributeExpression(LastNameAttribute, "T|U"),
+            AttributeExpression(FirstNameAttribute, "T|S(0,3)|U"),
+            AttributeExpression(SexAttribute, "T|U"),
+        ]
+
+    def get_identifier(self) -> str:
+        """Get the unique identifier for the token."""
+        return self.ID
+
+    def get_definition(self) -> List[AttributeExpression]:
+        """Get the list of attribute expressions that define the token."""
+        return self._definition

openlinktoken/tokens/token.py

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: MIT
+
+from abc import ABC, abstractmethod
+from typing import List
+
+from openlinktoken.attributes.attribute_expression import AttributeExpression
+
+
+class Token(ABC):
+    """
+    A token is a collection of attribute expressions that are concatenated
+    together to get the token signature and a unique identifier.
+    """
+
+    # Represents the value for tokens with invalid or missing data.
+    # This constant is a placeholder for cases where a token is either
+    # not provided or contains invalid information.
+    BLANK = "0000000000000000000000000000000000000000000000000000000000000000"
+
+    @abstractmethod
+    def get_identifier(self) -> str:
+        """
+        Get the unique identifier for the token.
+
+        Returns:
+            The unique identifier for the token.
+        """
+        pass
+
+    @abstractmethod
+    def get_definition(self) -> List[AttributeExpression]:
+        """
+        Get the list of attribute expressions that define the token.
+
+        Returns:
+            The list of attribute expressions that define the token.
+        """
+        pass

openlinktoken/tokens/token_definition.py

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: MIT
+
+from typing import Dict, List, Set
+
+from openlinktoken.attributes.attribute_expression import AttributeExpression
+from openlinktoken.tokens.base_token_definition import BaseTokenDefinition
+
+
+class TokenDefinition(BaseTokenDefinition):
+    """
+    Encapsulates the token definitions.
+
+    The tokens are generated using some token generation rules. This class
+    encapsulates the definition of those rules. Together, they are commonly
+    referred to as token definitions or rule definitions.
+
+    Each token/rule definition is a collection of AttributeExpression that are
+    concatenated together to get the token signature.
+    """
+
+    def __init__(self):
+        """
+        Initializes the token definitions.
+        Loads all token definitions using TokenRegistry.
+        """
+        from openlinktoken.tokens.token_registry import TokenRegistry
+
+        self.definitions: Dict[str, List[AttributeExpression]] = TokenRegistry.load_all_tokens()
+
+    def get_version(self) -> str:
+        """
+        Get the version of the token definition.
+        """
+        return "2.0"
+
+    def get_token_identifiers(self) -> Set[str]:
+        """
+        Get all token identifiers.
+        """
+        return set(self.definitions.keys())
+
+    def get_token_definition(self, token_id: str) -> List[AttributeExpression]:
+        """
+        Get the token definition for a given token identifier.
+        """
+        return self.definitions.get(token_id)

openlinktoken/tokens/token_generation_exception.py

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: MIT
+
+
+class TokenGenerationException(Exception):
+    """Exception raised when token generation fails."""
+
+    def __init__(self, message: str, cause: Exception = None):
+        """
+        Initialize the exception.
+
+        Args:
+            message: The error message.
+            cause: The underlying cause of the exception.
+        """
+        super().__init__(message)
+        self.cause = cause

openlinktoken/tokens/token_generator.py

@@ -0,0 +1,201 @@
+# SPDX-License-Identifier: MIT
+
+import logging
+from typing import Dict, List, Optional, Set, Type
+
+from openlinktoken.attributes.attribute import Attribute
+from openlinktoken.attributes.attribute_loader import AttributeLoader
+from openlinktoken.tokens.base_token_definition import BaseTokenDefinition
+from openlinktoken.tokens.token import Token
+from openlinktoken.tokens.token_generation_exception import TokenGenerationException
+from openlinktoken.tokens.token_generator_result import TokenGeneratorResult
+from openlinktoken.tokens.tokenizer.sha256_tokenizer import SHA256Tokenizer
+from openlinktoken.tokens.tokenizer.tokenizer import Tokenizer
+from openlinktoken.tokentransformer.token_transformer import TokenTransformer
+
+logger = logging.getLogger(__name__)
+
+
+class TokenGenerator:
+    """Generates both the token signature and the token itself."""
+
+    @classmethod
+    def from_transformers(
+        cls, token_definition: BaseTokenDefinition, token_transformer_list: List[TokenTransformer]
+    ) -> "TokenGenerator":
+        """
+        Convenience constructor that creates a TokenGenerator with SHA256Tokenizer.
+
+        Args:
+            token_definition: The token definition.
+            token_transformer_list: A list of token transformers.
+
+        Returns:
+            A TokenGenerator instance with SHA256Tokenizer.
+        """
+        return cls(token_definition, SHA256Tokenizer(token_transformer_list))
+
+    def __init__(self, token_definition: BaseTokenDefinition, tokenizer: Tokenizer):
+        """
+        Initialize the token generator with an explicit tokenizer.
+
+        Args:
+            token_definition: The token definition.
+            tokenizer: Tokenizer implementation. Use PassthroughTokenizer for plain mode.
+        """
+        self.token_definition = token_definition
+        self.attribute_instance_map: Dict[Type[Attribute], Attribute] = {}
+
+        # Load attributes
+        for attribute in AttributeLoader.load():
+            self.attribute_instance_map[type(attribute)] = attribute
+
+        self.tokenizer = tokenizer
+
+    def _get_token_signature(
+        self, token_id: str, person_attributes: Dict[Type[Attribute], str], result: TokenGeneratorResult
+    ) -> Optional[str]:
+        """
+        Get the token signature for a given token identifier.
+
+        Populates the invalid_attributes list in the result object with the attributes
+        that are invalid.
+
+        Args:
+            token_id: The token identifier.
+            person_attributes: The person attributes map.
+            result: The token generator result.
+
+        Returns:
+            The token signature using the token definition for the given token identifier.
+        """
+        definition = self.token_definition.get_token_definition(token_id)
+
+        if person_attributes is None:
+            raise ValueError("Person attributes cannot be null.")
+
+        values = []
+
+        for attribute_expression in definition:
+            attribute_class = attribute_expression.attribute_class
+
+            if attribute_class not in person_attributes:
+                return None
+
+            attribute = self.attribute_instance_map.get(attribute_class)
+            if attribute is None:
+                return None
+
+            attribute_value = person_attributes[attribute_class]
+
+            if not attribute.validate(attribute_value):
+                result.invalid_attributes.add(attribute.get_name())
+                return None
+
+            attribute_value = attribute.normalize(attribute_value)
+
+            try:
+                attribute_value = attribute_expression.get_effective_value(attribute_value)
+                values.append(attribute_value)
+            except ValueError as e:
+                logger.error(str(e))
+                return None
+
+        # Filter out None and blank values, then join with '|'
+        filtered_values = [v for v in values if v is not None and v.strip() != ""]
+        return "|".join(filtered_values)
+
+    def get_all_token_signatures(self, person_attributes: Dict[Type[Attribute], str]) -> Dict[str, str]:
+        """
+        Get the token signatures for all token/rule identifiers.
+
+        This is mostly a debug/logging/test method.
+
+        Args:
+            person_attributes: The person attributes map.
+
+        Returns:
+            A map of token/rule identifier to the token signature.
+        """
+        signatures = {}
+
+        for token_id in self.token_definition.get_token_identifiers():
+            try:
+                signature = self._get_token_signature(token_id, person_attributes, TokenGeneratorResult())
+                if signature is not None:
+                    signatures[token_id] = signature
+            except Exception as e:
+                logger.error(f"Error generating token signature for token id: {token_id}", exc_info=e)
+
+        return signatures
+
+    def _get_token(
+        self, token_id: str, person_attributes: Dict[Type[Attribute], str], result: TokenGeneratorResult
+    ) -> Optional[str]:
+        """
+        Get token for a given token identifier.
+
+        Args:
+            token_id: The token identifier.
+            person_attributes: The person attributes map.
+            result: The token generator result.
+
+        Returns:
+            The token using the token definition for the given token identifier.
+
+        Raises:
+            TokenGenerationException: In case of failure to generate the token.
+        """
+        signature = self._get_token_signature(token_id, person_attributes, result)
+        logger.debug(f"Token signature for token id {token_id}: {signature}")
+
+        try:
+            token = self.tokenizer.tokenize(signature)
+            # Track blank tokens by rule
+            if Token.BLANK == token:
+                result.blank_tokens_by_rule.add(token_id)
+            return token
+        except Exception as e:
+            logger.error(f"Error generating token for token id: {token_id}", exc_info=e)
+            raise TokenGenerationException("Error generating token", e)
+
+    def get_all_tokens(self, person_attributes: Dict[Type[Attribute], str]) -> TokenGeneratorResult:
+        """
+        Get the tokens for all token/rule identifiers.
+
+        Args:
+            person_attributes: The person attributes map.
+
+        Returns:
+            A TokenGeneratorResult object containing the tokens and invalid attributes.
+        """
+        result = TokenGeneratorResult()
+
+        for token_id in self.token_definition.get_token_identifiers():
+            try:
+                token = self._get_token(token_id, person_attributes, result)
+                if token is not None:
+                    result.tokens[token_id] = token
+            except Exception as e:
+                logger.error(f"Error generating token for token id: {token_id}", exc_info=e)
+
+        return result
+
+    def get_invalid_person_attributes(self, person_attributes: Dict[Type[Attribute], str]) -> Set[str]:
+        """
+        Get invalid person attribute names.
+
+        Args:
+            person_attributes: The person attributes map.
+
+        Returns:
+            A set of invalid person attribute names.
+        """
+        response = set()
+
+        for attribute_class, value in person_attributes.items():
+            attribute = self.attribute_instance_map.get(attribute_class)
+            if attribute and not attribute.validate(value):
+                response.add(attribute.get_name())
+
+        return response