openlinktoken 2.0.0__py3-none-any.whl

openlinktoken/tokens/token_generator_result.py

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: MIT
+
+from typing import Dict, Set
+
+
+class TokenGeneratorResult:
+    """
+    Represents the result of a token generation operation.
+
+    This class contains the generated tokens, the list of invalid attributes,
+    and the count of blank tokens generated by rule.
+    """
+
+    def __init__(self):
+        """Initialize the result with empty collections."""
+        self._tokens: Dict[str, str] = {}
+        self._invalid_attributes: Set[str] = set()
+        self._blank_tokens_by_rule: Set[str] = set()
+
+    @property
+    def tokens(self) -> Dict[str, str]:
+        """Get the generated tokens."""
+        return self._tokens
+
+    @property
+    def invalid_attributes(self) -> Set[str]:
+        """Get the invalid attributes."""
+        return self._invalid_attributes
+
+    @property
+    def blank_tokens_by_rule(self) -> Set[str]:
+        """Get the blank tokens by rule."""
+        return self._blank_tokens_by_rule

openlinktoken/tokens/token_registry.py

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: MIT
+
+import importlib
+import pkgutil
+from importlib import resources
+from typing import Dict, List
+
+from openlinktoken.attributes.attribute_expression import AttributeExpression
+from openlinktoken.tokens.token import Token
+
+
+class TokenRegistry:
+    @staticmethod
+    def load_all_tokens() -> Dict[str, List[AttributeExpression]]:
+        definitions: Dict[str, List[AttributeExpression]] = {}
+
+        package_name = "openlinktoken.tokens.definitions"
+        package = importlib.import_module(package_name)
+
+        module_names: List[str] = []
+        package_path = getattr(package, "__path__", None)
+        if package_path is not None:
+            try:
+                module_names = [module_info.name for module_info in pkgutil.iter_modules(package_path)]
+            except Exception:
+                module_names = []
+
+        if not module_names:
+            try:
+                module_names = [
+                    item.name[:-3]
+                    for item in resources.files(package).iterdir()
+                    if item.name.endswith(".py") and item.name != "__init__.py"
+                ]
+            except Exception:
+                module_names = ["t1_token", "t2_token", "t3_token", "t4_token", "t5_token"]
+
+        for module_name in module_names:
+            module = importlib.import_module(f"{package_name}.{module_name}")
+
+            for obj in module.__dict__.values():
+                if isinstance(obj, type) and issubclass(obj, Token) and obj is not Token:
+                    token = obj()
+                    definitions[token.get_identifier()] = token.get_definition()
+
+        return definitions

openlinktoken/tokens/tokenizer/__init__.py

@@ -0,0 +1,11 @@
+"""Tokenizer implementations for token generation."""
+
+from .passthrough_tokenizer import PassthroughTokenizer
+from .sha256_tokenizer import SHA256Tokenizer
+from .tokenizer import Tokenizer
+
+__all__ = [
+    "PassthroughTokenizer",
+    "SHA256Tokenizer",
+    "Tokenizer",
+]

openlinktoken/tokens/tokenizer/passthrough_tokenizer.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: MIT
+
+from typing import List
+
+from openlinktoken.tokens.token import Token
+from openlinktoken.tokens.tokenizer.tokenizer import Tokenizer
+from openlinktoken.tokentransformer.token_transformer import TokenTransformer
+
+
+class PassthroughTokenizer(Tokenizer):
+    """
+    A tokenizer that returns the input value unchanged (passthrough).
+
+    This tokenizer does not apply any hashing or cryptographic transformation
+    to the input value. It simply returns the input as-is, optionally applying
+    token transformers if provided.
+
+    This is useful for scenarios where you want to preserve the original token
+    signature without any cryptographic processing, while still allowing for
+    optional transformations (e.g., encryption).
+    """
+
+    EMPTY = Token.BLANK
+    """
+    The empty token value.
+
+    This is the value returned when the token signature is None or blank.
+    """
+
+    def __init__(self, token_transformer_list: List[TokenTransformer]):
+        """
+        Initialize the tokenizer.
+
+        Args:
+            token_transformer_list: A list of token transformers.
+        """
+        self.token_transformer_list = token_transformer_list
+
+    def tokenize(self, value: str) -> str:
+        """
+        Return the input value unchanged (passthrough).
+
+        Token = value
+
+        The token is optionally transformed with one or more transformers.
+
+        Args:
+            value: The token signature value.
+
+        Returns:
+            The token. If the token signature value is None or blank,
+            EMPTY is returned.
+
+        Raises:
+            Exception: If an error is thrown by the transformer.
+        """
+        if value is None or value.strip() == "":
+            return self.EMPTY
+
+        transformed_token = value
+
+        # Apply transformers
+        for token_transformer in self.token_transformer_list:
+            transformed_token = token_transformer.transform(transformed_token)
+
+        return transformed_token

openlinktoken/tokens/tokenizer/sha256_tokenizer.py

@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: MIT
+
+import hashlib
+from typing import List
+
+from openlinktoken.tokens.token import Token
+from openlinktoken.tokens.tokenizer.tokenizer import Tokenizer
+from openlinktoken.tokentransformer.token_transformer import TokenTransformer
+
+
+class SHA256Tokenizer(Tokenizer):
+    """
+    Generates token using SHA256 digest.
+
+    The token is generated using SHA256 digest and is hex encoded.
+    If token transformations are specified, the token is then transformed
+    by those transformers.
+    """
+
+    EMPTY = Token.BLANK
+    """
+    The empty token value.
+
+    This is the value returned when the token signature is None or blank.
+    """
+
+    def __init__(self, token_transformer_list: List[TokenTransformer]):
+        """
+        Initialize the tokenizer.
+
+        Args:
+            token_transformer_list: A list of token transformers.
+        """
+        self.token_transformer_list = token_transformer_list
+
+    def tokenize(self, value: str) -> str:
+        """
+        Generate the token for the given token signature.
+
+        Token = Hex(Sha256(token-signature))
+
+        The token is optionally transformed with one or more transformers.
+
+        Args:
+            value: The token signature value.
+
+        Returns:
+            The token. If the token signature value is None or blank,
+            EMPTY is returned.
+
+        Raises:
+            Exception: If an error is thrown by the transformer.
+        """
+        if value is None or value.strip() == "":
+            return self.EMPTY
+
+        # Convert string to bytes using UTF-8 encoding
+        value_bytes = value.encode("utf-8")
+
+        # Create SHA-256 hash
+        digest = hashlib.sha256()
+        digest.update(value_bytes)
+        hash_bytes = digest.digest()
+
+        # Convert to hex string
+        transformed_token = hash_bytes.hex()
+
+        # Apply transformers
+        for token_transformer in self.token_transformer_list:
+            transformed_token = token_transformer.transform(transformed_token)
+
+        return transformed_token

openlinktoken/tokens/tokenizer/tokenizer.py

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: MIT
+
+from abc import ABC, abstractmethod
+
+
+class Tokenizer(ABC):
+    """
+    Interface for tokenizing values into tokens.
+
+    A tokenizer takes a string value (typically a token signature) and
+    transforms it into a token using various cryptographic or encoding
+    techniques.
+    """
+
+    @abstractmethod
+    def tokenize(self, value: str) -> str:
+        """
+        Generate a token from the given value.
+
+        Args:
+            value: The value to tokenize (e.g., a token signature).
+
+        Returns:
+            The generated token. Returns a default empty token value
+            if the input value is null or blank.
+
+        Raises:
+            Exception: If an error occurs during tokenization, such as
+                       unsupported encoding or cryptographic algorithm issues.
+        """
+        pass

openlinktoken/tokentransformer/__init__.py

@@ -0,0 +1,43 @@
+"""Token transformer implementations for Open Link Token."""
+
+from .decrypt_token_transformer import DecryptTokenTransformer
+from .encrypt_token_transformer import EncryptTokenTransformer
+from .hash_token_transformer import HashTokenTransformer
+from .match_token_constants import (
+    HEADER_KEY_ALGORITHM,
+    HEADER_KEY_ENCRYPTION,
+    HEADER_KEY_KEY_ID,
+    HEADER_KEY_TYPE,
+    PAYLOAD_KEY_HASH_ALGORITHM,
+    PAYLOAD_KEY_ISSUED_AT,
+    PAYLOAD_KEY_ISSUER,
+    PAYLOAD_KEY_MAC_ALGORITHM,
+    PAYLOAD_KEY_PPID,
+    PAYLOAD_KEY_RING_ID,
+    PAYLOAD_KEY_RULE_ID,
+    TOKEN_TYPE,
+    V1_TOKEN_PREFIX,
+)
+from .no_operation_token_transformer import NoOperationTokenTransformer
+from .token_transformer import TokenTransformer
+
+__all__ = [
+    "DecryptTokenTransformer",
+    "EncryptTokenTransformer",
+    "HashTokenTransformer",
+    "HEADER_KEY_ALGORITHM",
+    "HEADER_KEY_ENCRYPTION",
+    "HEADER_KEY_KEY_ID",
+    "HEADER_KEY_TYPE",
+    "PAYLOAD_KEY_HASH_ALGORITHM",
+    "PAYLOAD_KEY_ISSUED_AT",
+    "PAYLOAD_KEY_ISSUER",
+    "PAYLOAD_KEY_MAC_ALGORITHM",
+    "PAYLOAD_KEY_PPID",
+    "PAYLOAD_KEY_RING_ID",
+    "PAYLOAD_KEY_RULE_ID",
+    "TOKEN_TYPE",
+    "V1_TOKEN_PREFIX",
+    "NoOperationTokenTransformer",
+    "TokenTransformer",
+]

openlinktoken/tokentransformer/decrypt_token_transformer.py

@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: MIT
+
+import base64
+import logging
+from typing import Union
+
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+from openlinktoken.tokentransformer.encryption_constants import EncryptionConstants
+from openlinktoken.tokentransformer.token_transformer import TokenTransformer
+
+logger = logging.getLogger(__name__)
+
+
+class DecryptTokenTransformer(TokenTransformer):
+    """AES-256 GCM token decryption transformer.
+
+    Parity with Java `DecryptTokenTransformer`:
+    - Java prepends IV to (ciphertext || tag) and GCM consumes combined remainder.
+    - Python splits IV, ciphertext, and tag explicitly before constructing GCM mode.
+    - Both expect 12-byte IV and 16-byte tag; key length enforced at init.
+    """
+
+    def __init__(self, encryption_key: Union[str, bytes]):
+        """
+        Initializes the underlying cipher (AES) with the decryption secret.
+
+        Accepts either a ``str`` (UTF-8 encoded; must encode to exactly 32 bytes) or
+        raw ``bytes`` (must be exactly 32 bytes).
+
+        Args:
+            encryption_key: The encryption key. The UTF-8 encoded key material must be exactly 32 bytes long.
+
+        Raises:
+            ValueError: If the encryption key material is not exactly 32 bytes long.
+        """
+        if isinstance(encryption_key, bytes):
+            if len(encryption_key) != EncryptionConstants.KEY_BYTE_LENGTH:
+                logger.error(f"Invalid Argument. Key must be {EncryptionConstants.KEY_BYTE_LENGTH} bytes long")
+                raise ValueError(f"Key must be {EncryptionConstants.KEY_BYTE_LENGTH} bytes long")
+            self.encryption_key = encryption_key
+        else:
+            encryption_key_bytes = encryption_key.encode("utf-8")
+            if len(encryption_key_bytes) != EncryptionConstants.KEY_BYTE_LENGTH:
+                logger.error(f"Invalid Argument. Key must be {EncryptionConstants.KEY_BYTE_LENGTH} bytes long")
+                raise ValueError(f"Key must be {EncryptionConstants.KEY_BYTE_LENGTH} bytes long")
+            self.encryption_key = encryption_key_bytes
+
+    def transform(self, token: str) -> str:
+        """Decrypt a base64 encoded token produced by the encrypt transformer.
+
+        Args:
+            token: Base64 string containing IV || ciphertext || tag.
+
+        Returns:
+            Decrypted UTF-8 token string.
+
+        Raises:
+            Exception: Propagates cryptographic failures (logged here first).
+        """
+        try:
+            # Decode the base64-encoded token
+            message_bytes = base64.b64decode(token)
+
+            # Extract IV, encrypted data, and tag
+            iv_bytes = message_bytes[: EncryptionConstants.IV_SIZE]
+            ciphertext_and_tag = message_bytes[EncryptionConstants.IV_SIZE :]
+            ciphertext = ciphertext_and_tag[: -EncryptionConstants.TAG_LENGTH_BYTES]
+            tag = ciphertext_and_tag[-EncryptionConstants.TAG_LENGTH_BYTES :]
+
+            # Create cipher for decryption
+            cipher = Cipher(algorithms.AES(self.encryption_key), modes.GCM(iv_bytes, tag), backend=default_backend())
+
+            # Decrypt the token
+            decryptor = cipher.decryptor()
+            decrypted_bytes = decryptor.update(ciphertext) + decryptor.finalize()
+
+            return decrypted_bytes.decode("utf-8")
+
+        except Exception as e:
+            logger.error("Error during token decryption", exc_info=e)
+            raise

openlinktoken/tokentransformer/encrypt_token_transformer.py

@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: MIT
+
+import base64
+import logging
+import secrets
+from typing import Union
+
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+from openlinktoken.tokentransformer.encryption_constants import EncryptionConstants
+from openlinktoken.tokentransformer.token_transformer import TokenTransformer
+
+logger = logging.getLogger(__name__)
+
+
+class EncryptTokenTransformer(TokenTransformer):
+    """
+    Transforms the token using AES-256 symmetric encryption.
+
+    See: https://datatracker.ietf.org/doc/html/rfc3826 (AES)
+    """
+
+    def __init__(self, encryption_key: Union[str, bytes]):
+        """
+        Initializes the underlying cipher (AES) with the encryption secret.
+
+        Accepts either a ``str`` (UTF-8 encoded; must encode to exactly 32 bytes) or
+        raw ``bytes`` (must be exactly 32 bytes).
+
+        Args:
+            encryption_key: The encryption key. The UTF-8 encoded key material must be exactly 32 bytes long.
+
+        Raises:
+            ValueError: If the encryption key material is not exactly 32 bytes long.
+        """
+        if isinstance(encryption_key, bytes):
+            if len(encryption_key) != EncryptionConstants.KEY_BYTE_LENGTH:
+                logger.error(f"Invalid Argument. Key must be {EncryptionConstants.KEY_BYTE_LENGTH} bytes long")
+                raise ValueError(f"Key must be {EncryptionConstants.KEY_BYTE_LENGTH} bytes long")
+            self.encryption_key = encryption_key
+        else:
+            encryption_key_bytes = encryption_key.encode("utf-8")
+            if len(encryption_key_bytes) != EncryptionConstants.KEY_BYTE_LENGTH:
+                logger.error(f"Invalid Argument. Key must be {EncryptionConstants.KEY_BYTE_LENGTH} bytes long")
+                raise ValueError(f"Key must be {EncryptionConstants.KEY_BYTE_LENGTH} bytes long")
+            self.encryption_key = encryption_key_bytes
+
+    def transform(self, token: str) -> str:
+        """
+        Encryption token transformer.
+
+        Encrypts the token using AES-256 symmetric encryption algorithm.
+
+        Args:
+            token: The token to be encrypted.
+
+        Returns:
+            The encrypted token in base64 format.
+
+        Raises:
+            Exception: If encryption fails due to various cryptographic errors.
+        """
+        try:
+            # Generate random IV (for AES GCM mode)
+            iv_bytes = secrets.token_bytes(EncryptionConstants.IV_SIZE)
+
+            # Create cipher
+            cipher = Cipher(algorithms.AES(self.encryption_key), modes.GCM(iv_bytes), backend=default_backend())
+
+            # Encrypt the token
+            encryptor = cipher.encryptor()
+            encrypted_bytes = encryptor.update(token.encode("utf-8")) + encryptor.finalize()
+
+            # Get the authentication tag
+            tag = encryptor.tag
+
+            # Combine IV + encrypted data + tag
+            message_bytes = iv_bytes + encrypted_bytes + tag
+
+            return base64.b64encode(message_bytes).decode("utf-8")
+
+        except Exception as e:
+            logger.error(f"Error during token encryption: {e}")
+            raise

openlinktoken/tokentransformer/encryption_constants.py

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: MIT
+
+
+class EncryptionConstants:
+    """Shared constants for AES-256 GCM encryption and decryption."""
+
+    # AES algorithm name
+    AES = "AES"
+
+    # AES-256 GCM encryption algorithm specification
+    ENCRYPTION_ALGORITHM = "AES/GCM/NoPadding"
+
+    # AES-256 key length in bytes
+    KEY_BYTE_LENGTH = 32
+
+    # GCM initialization vector size in bytes
+    IV_SIZE = 12
+
+    # GCM authentication tag length in bits
+    TAG_LENGTH_BITS = 128
+
+    # GCM authentication tag length in bytes (128 bits = 16 bytes)
+    TAG_LENGTH_BYTES = 16

openlinktoken/tokentransformer/hash_token_transformer.py

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: MIT
+
+import base64
+import hashlib
+import hmac
+import logging
+import threading
+from typing import Union
+
+from openlinktoken.tokentransformer.token_transformer import TokenTransformer
+
+logger = logging.getLogger(__name__)
+
+
+class HashTokenTransformer(TokenTransformer):
+    """
+    Transforms the token using a cryptographic hash function with
+    a secret key.
+
+    See: https://datatracker.ietf.org/doc/html/rfc4868 (HMACSHA256)
+    """
+
+    def __init__(self, hashing_secret: Union[str, bytes, None]):
+        """
+        Initializes the underlying MAC with the secret key.
+
+        Accepts a ``str`` (encoded to UTF-8), raw ``bytes``, or ``None`` / empty
+        to create a no-op transformer (``transform`` will raise ``RuntimeError``).
+
+        Args:
+            hashing_secret: The cryptographic secret key.
+
+        Raises:
+            ValueError: If the hashing secret is None or empty.
+        """
+        self._lock = threading.Lock()
+        if isinstance(hashing_secret, bytes):
+            self.hashing_secret = hashing_secret
+            self._mac_available = len(hashing_secret) > 0
+        elif not hashing_secret or hashing_secret.strip() == "":
+            self.hashing_secret = b""
+            self._mac_available = False
+        else:
+            self.hashing_secret = hashing_secret.encode("utf-8")
+            self._mac_available = True
+
+    def transform(self, token: str) -> str:
+        """
+        Hash token transformer.
+
+        The token is transformed using HMAC SHA256 algorithm.
+
+        Args:
+            token: The token to be transformed.
+
+        Returns:
+            Hashed token in base64 format.
+
+        Raises:
+            ValueError: If token is None or blank.
+            RuntimeError: If the HMAC is not initialized properly.
+        """
+        if token is None or token.strip() == "":
+            logger.error("Invalid Argument. Token can't be None or blank.")
+            raise ValueError("Invalid Argument. Token can't be None or blank.")
+
+        if not self._mac_available:
+            raise RuntimeError("HMAC is not properly initialized due to empty hashing secret.")
+
+        with self._lock:
+            mac = hmac.new(self.hashing_secret, token.encode("utf-8"), hashlib.sha256)
+
+            # Get the digest and encode to base64
+            digest = mac.digest()
+            return base64.b64encode(digest).decode("utf-8")
+
+    def __getstate__(self):
+        """Custom serialization support."""
+        state = self.__dict__.copy()
+        # Remove the lock as it can't be pickled
+        del state["_lock"]
+        return state
+
+    def __setstate__(self, state):
+        """Custom deserialization support."""
+        self.__dict__.update(state)
+        # Recreate the lock
+        self._lock = threading.Lock()