clm-kernel 0.0.0__py3-none-any.whl

clm/layer0/model/handle.py

@@ -0,0 +1,163 @@
+"""Content Handle system for MCard.
+
+A ContentHandle provides a mutable pointer to immutable MCard content,
+enabling human-friendly naming and versioning while preserving data immutability.
+
+## UTF-8 Support
+Handles support Unicode characters for internationalization:
+- Must start with a Unicode letter (any language)
+- Can contain letters, digits, underscores, and hyphens
+- Maximum 63 characters
+- Normalized to NFC (Canonical Decomposition, then Canonical Composition)
+
+Examples: "my_doc", "文檔", "مستند", "ドキュメント", "документ"
+"""
+
+import logging
+import unicodedata
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger(__name__)
+
+# Maximum handle length
+MAX_HANDLE_LENGTH = 255
+
+
+def _is_valid_start_char(char: str) -> bool:
+    """Check if character is valid as the first character of a handle.
+
+    Must be a Unicode letter (category 'L').
+    """
+    return unicodedata.category(char).startswith("L")
+
+
+def _is_valid_body_char(char: str) -> bool:
+    """Check if character is valid in the body of a handle.
+
+    Can be: letter, number, underscore, hyphen.
+    """
+    cat = unicodedata.category(char)
+    return (
+        cat.startswith("L")  # Letters (any language)
+        or cat.startswith("N")  # Numbers (any language)
+        or char == "_"  # Underscore
+        or char == "-"  # Hyphen
+        or char == "."  # Dot
+        or char == "/"  # Forward slash
+        or char == " "  # Space
+        or char == ":"  # Colon (for URIs)
+    )
+
+
+class HandleValidationError(ValueError):
+    """Raised when a handle string is invalid."""
+
+    pass
+
+
+def validate_handle(handle: str) -> str:
+    """Validate and normalize a handle string.
+
+    Args:
+        handle: The handle string to validate.
+
+    Returns:
+        The validated and normalized handle (NFC normalized, case-preserving).
+
+    Raises:
+        HandleValidationError: If the handle is invalid.
+    """
+    if not handle:
+        raise HandleValidationError("Handle cannot be empty.")
+
+    # Normalize: strip whitespace, apply Unicode NFC normalization (case-preserving)
+    normalized = unicodedata.normalize("NFC", handle.strip())
+
+    if len(normalized) > MAX_HANDLE_LENGTH:
+        raise HandleValidationError(
+            f"Handle '{handle}' is too long ({len(normalized)} chars). "
+            f"Maximum length is {MAX_HANDLE_LENGTH} characters."
+        )
+
+    if len(normalized) == 0:
+        raise HandleValidationError("Handle cannot be empty after normalization.")
+
+    # Validate first character
+    if not _is_valid_start_char(normalized[0]):
+        raise HandleValidationError(
+            f"Invalid handle '{handle}'. Must start with a letter (any language)."
+        )
+
+    # Validate remaining characters
+    for i, char in enumerate(normalized[1:], start=1):
+        if not _is_valid_body_char(char):
+            raise HandleValidationError(
+                f"Invalid character '{char}' at position {i} in handle '{handle}'. "
+                "Allowed: letters, digits, underscores, hyphens."
+            )
+
+    return normalized
+
+
+class ContentHandle:
+    """A mutable pointer to an immutable MCard hash.
+
+    Attributes:
+        handle: The validated handle string.
+        current_hash: The hash of the MCard this handle points to.
+        created_at: When this handle was first created.
+        updated_at: When this handle was last updated to point to a new hash.
+    """
+
+    def __init__(
+        self,
+        handle: str,
+        current_hash: str,
+        created_at: datetime | None = None,
+        updated_at: datetime | None = None,
+    ):
+        """Initialize a ContentHandle.
+
+        Args:
+            handle: The user-defined handle string (will be validated).
+            current_hash: The MCard hash this handle points to.
+            created_at: Creation timestamp (defaults to now).
+            updated_at: Last update timestamp (defaults to created_at).
+        """
+        self.handle = validate_handle(handle)
+        self.current_hash = current_hash
+        self.created_at = created_at or datetime.now(timezone.utc)
+        self.updated_at = updated_at or self.created_at
+
+    def update(self, new_hash: str) -> str:
+        """Update the handle to point to a new hash.
+
+        Args:
+            new_hash: The new MCard hash to point to.
+
+        Returns:
+            The previous hash (for history tracking).
+        """
+        previous_hash = self.current_hash
+        self.current_hash = new_hash
+        self.updated_at = datetime.now(timezone.utc)
+        logger.info(
+            f"Handle '{self.handle}' updated: {previous_hash[:8]}... -> {new_hash[:8]}..."
+        )
+        return previous_hash
+
+    def __repr__(self) -> str:
+        return f"ContentHandle(handle='{self.handle}', current_hash='{self.current_hash[:8]}...')"
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary representation."""
+        return {
+            "handle": self.handle,
+            "current_hash": self.current_hash,
+            "created_at": self.created_at.isoformat(),
+            "updated_at": self.updated_at.isoformat(),
+        }

clm/layer0/model/hash/__init__.py

@@ -0,0 +1,6 @@
+"""Hash module for MCard."""
+
+from .constants import HASH_ALGORITHM_HIERARCHY
+from .enums import HashAlgorithm
+
+__all__ = ["HashAlgorithm", "HASH_ALGORITHM_HIERARCHY"]

clm/layer0/model/hash/algorithms/__init__.py

@@ -0,0 +1,3 @@
+from ..validator import HashValidator
+
+__all__ = ["HashValidator"]

clm/layer0/model/hash/algorithms/custom_hash.py

@@ -0,0 +1,7 @@
+# Custom hash algorithms can be implemented here.
+
+
+class MyCustomHash:
+    def compute(self, content: bytes) -> str:
+        # Implement your custom hashing logic here
+        return "custom_hash_value"

clm/layer0/model/hash/algorithms/local_sha256.py

@@ -0,0 +1,178 @@
+import struct
+
+# SHA-256 constants
+K = [
+    0x428A2F98,
+    0x71374491,
+    0xB5C0FBCF,
+    0xE9B5DBA5,
+    0x3956C25B,
+    0x59F111F1,
+    0x923F82A4,
+    0xAB1C5ED5,
+    0xD807AA98,
+    0x12835B01,
+    0x243185BE,
+    0x550C7DC3,
+    0x72BE5D74,
+    0x80DEB1FE,
+    0x9BDC06A7,
+    0xC19BF174,
+    0xE49B69C1,
+    0xEFBE4786,
+    0x0FC19DC6,
+    0x240CA1CC,
+    0x2DE92C6F,
+    0x4A7484AA,
+    0x5CB0A9DC,
+    0x76F988DA,
+    0x983E5152,
+    0xA831C66D,
+    0xB00327C8,
+    0xBF597FC7,
+    0xC6E00BF3,
+    0xD5A79147,
+    0x06CA6351,
+    0x14292967,
+    0x27B70A85,
+    0x2E1B2138,
+    0x4D2C6DFC,
+    0x53380D13,
+    0x650A7354,
+    0x766A0ABB,
+    0x81C2C92E,
+    0x92722C85,
+    0xA2BFE8A1,
+    0xA81A664B,
+    0xC24B8B70,
+    0xC76C51A3,
+    0xD192E819,
+    0xD6990624,
+    0xF40E3585,
+    0x106AA070,
+    0x19A4C116,
+    0x1E376C08,
+    0x2748774C,
+    0x34B0BCB5,
+    0x391C0CB3,
+    0x4ED8AA4A,
+    0x5B9CCA4F,
+    0x682E6FF3,
+    0x748F82EE,
+    0x78A5636F,
+    0x84C87814,
+    0x8CC70208,
+    0x90BEFFFA,
+    0xA4506CEB,
+    0xBEF9A3F7,
+    0xC67178F2,
+]
+
+# Initial hash values
+H = [
+    0x6A09E667,
+    0xBB67AE85,
+    0x3C6EF372,
+    0xA54FF53A,
+    0x510E527F,
+    0x9B05688C,
+    0x1F83D9AB,
+    0x5BE0CD19,
+]
+
+
+def right_rotate(value, shift):
+    """Perform a right circular rotation on a 32-bit integer."""
+    return ((value >> shift) | (value << (32 - shift))) & 0xFFFFFFFF
+
+
+def localized_sha256(message):
+    """Compute the SHA-256 hash of a message."""
+    global H
+    H = [
+        0x6A09E667,
+        0xBB67AE85,
+        0x3C6EF372,
+        0xA54FF53A,
+        0x510E527F,
+        0x9B05688C,
+        0x1F83D9AB,
+        0x5BE0CD19,
+    ]
+
+    # Ensure message is in bytes
+    if isinstance(message, str):
+        message = message.encode("utf-8")
+    elif not isinstance(message, bytes):
+        raise TypeError("Input must be a string or bytes")
+
+    original_length_bits = len(message) * 8
+    message += b"\x80"
+
+    while (len(message) * 8) % 512 != 448:
+        message += b"\x00"
+
+    message += struct.pack(">Q", original_length_bits)
+
+    chunks = [message[i : i + 64] for i in range(0, len(message), 64)]
+
+    for chunk in chunks:
+        w = [0] * 64
+        for i in range(16):
+            w[i] = struct.unpack(">I", chunk[i * 4 : (i + 1) * 4])[0]
+
+        for i in range(16, 64):
+            s0 = (
+                right_rotate(w[i - 15], 7)
+                ^ right_rotate(w[i - 15], 18)
+                ^ (w[i - 15] >> 3)
+            )
+            s1 = (
+                right_rotate(w[i - 2], 17)
+                ^ right_rotate(w[i - 2], 19)
+                ^ (w[i - 2] >> 10)
+            )
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) & 0xFFFFFFFF
+
+        a, b, c, d, e, f, g, h = H[:]
+
+        for i in range(64):
+            S1 = right_rotate(e, 6) ^ right_rotate(e, 11) ^ right_rotate(e, 25)
+            ch = (e & f) ^ (~e & g)
+            temp1 = (h + S1 + ch + K[i] + w[i]) & 0xFFFFFFFF
+            S0 = right_rotate(a, 2) ^ right_rotate(a, 13) ^ right_rotate(a, 22)
+            maj = (a & b) ^ (a & c) ^ (b & c)
+            temp2 = (S0 + maj) & 0xFFFFFFFF
+
+            h = g
+            g = f
+            f = e
+            e = (d + temp1) & 0xFFFFFFFF
+            d = c
+            c = b
+            b = a
+            a = (temp1 + temp2) & 0xFFFFFFFF
+
+        H[0] = (H[0] + a) & 0xFFFFFFFF
+        H[1] = (H[1] + b) & 0xFFFFFFFF
+        H[2] = (H[2] + c) & 0xFFFFFFFF
+        H[3] = (H[3] + d) & 0xFFFFFFFF
+        H[4] = (H[4] + e) & 0xFFFFFFFF
+        H[5] = (H[5] + f) & 0xFFFFFFFF
+        H[6] = (H[6] + g) & 0xFFFFFFFF
+        H[7] = (H[7] + h) & 0xFFFFFFFF
+
+    return "".join(f"{h:08x}" for h in H)
+
+
+# Add debugging for the specific test case
+if __name__ == "__main__":
+    data = "The quick brown fox jumps over the lazy dog"
+    hash_value = localized_sha256(data)
+    print(f"Input: {data}")
+    print(f"SHA-256 Hash: {hash_value}")
+
+    # Compare with expected hash for debugging
+    expected_hash = "d7a8fbb307d7809469ca9abcb0082e4f2d0c0b5a0c0b5a0c0b5a0c0b5a0c0b5"
+    print(f"Expected SHA-256 Hash: {expected_hash}")
+    print(f"Match: {hash_value == expected_hash}")

clm/layer0/model/hash/constants.py

@@ -0,0 +1,53 @@
+"""Constants related to hash algorithms and operations."""
+
+from clm.layer0.model.hash.enums import HashAlgorithm
+
+# Hash Algorithm Hierarchy - Maps each algorithm to the set of stronger algorithms
+HASH_ALGORITHM_HIERARCHY = {
+    HashAlgorithm.MD5: {
+        HashAlgorithm.SHA1,
+        HashAlgorithm.SHA224,
+        HashAlgorithm.SHA256,
+        HashAlgorithm.SHA384,
+        HashAlgorithm.SHA512,
+        HashAlgorithm.BLAKE3,
+    },
+    HashAlgorithm.SHA1: {
+        HashAlgorithm.SHA224,
+        HashAlgorithm.SHA256,
+        HashAlgorithm.SHA384,
+        HashAlgorithm.SHA512,
+        HashAlgorithm.BLAKE3,
+    },
+    HashAlgorithm.SHA224: {
+        HashAlgorithm.SHA256,
+        HashAlgorithm.SHA384,
+        HashAlgorithm.SHA512,
+        HashAlgorithm.BLAKE3,
+    },
+    HashAlgorithm.SHA256: {
+        HashAlgorithm.SHA384,
+        HashAlgorithm.SHA512,
+        HashAlgorithm.BLAKE3,
+    },
+    HashAlgorithm.SHA384: {
+        HashAlgorithm.SHA512,
+        HashAlgorithm.BLAKE3,
+    },
+    HashAlgorithm.SHA512: {
+        HashAlgorithm.BLAKE3,
+    },
+    HashAlgorithm.BLAKE3: set(),
+}
+
+# Known MD5 collision pairs for testing
+KNOWN_MD5_COLLISION_PAIRS = [
+    (
+        bytes.fromhex(
+            "4dc968ff0ee35c209572d4777b721587d36fa7b21bdc56b74a3dc0783e7b9518afbfa200a8284bf36e8e4b55b35f427593d849676da0d1555d8360fb5f07fea2"
+        ),
+        bytes.fromhex(
+            "4dc968ff0ee35c209572d4777b721587d36fa7b21bdc56b74a3dc0783e7b9518afbfa202a8284bf36e8e4b55b35f427593d849676da0d1d55d8360fb5f07fea2"
+        ),
+    )
+]

clm/layer0/model/hash/enums.py

@@ -0,0 +1,60 @@
+"""Hash algorithm enums."""
+
+from enum import Enum
+
+
+class HashAlgorithm(Enum):
+    """Supported hash algorithms."""
+
+    MD5 = "md5"
+    SHA1 = "sha1"
+    SHA224 = "sha224"
+    SHA256 = "sha256"
+    SHA384 = "sha384"
+    SHA512 = "sha512"
+    BLAKE3 = "blake3"
+    CUSTOM = "custom"
+
+    # Default hash algorithm
+    DEFAULT = BLAKE3
+
+    @classmethod
+    def from_string(cls, value: str) -> "HashAlgorithm":
+        """Convert a string to a HashAlgorithm enum.
+
+        Args:
+            value: String value to convert
+
+        Returns:
+            HashAlgorithm: The corresponding enum value
+
+        Raises:
+            ValueError: If the string is not a valid hash algorithm
+        """
+        try:
+            return cls(value.lower())
+        except ValueError as e:
+            raise ValueError(f"'{value}' is not a valid hash algorithm") from e
+
+    @classmethod
+    def get_default(cls) -> "HashAlgorithm":
+        """Get the default hash algorithm from environment or fallback to SHA1."""
+        import os
+
+        env_algo = os.environ.get("MCARD_HASH_ALGORITHM")
+        if env_algo:
+            try:
+                return cls.from_string(env_algo)
+            except ValueError:
+                pass
+
+        try:
+            from clm.cross_cutting.config.settings import settings
+
+            env_algo = settings.hashing.algorithm
+            if env_algo:
+                return cls.from_string(env_algo)
+        except Exception:
+            pass
+
+        return cls.DEFAULT