iqcc-shared 0.1.0__py3-none-any.whl

iqcc_shared/__init__.py

@@ -0,0 +1,67 @@
+"""iqcc-shared — Symmetric Encryption with Post-Quantum Key Exchange.
+
+Provides hybrid encryption (ML-KEM-768 + AES-256-GCM),
+automated key rotation, and strict msgpack serialization.
+
+Key features:
+  • Post-quantum key encapsulation (ML-KEM-768)
+  • AES-256-GCM symmetric payload encryption with per-field auth tags
+  • Dot-notation path resolver with wildcard (``.*``) support
+  • Strict msgpack serialization with security hardening
+  • Automated key rotation with overlap window
+"""
+
+__version__ = "0.1.0"
+
+# ── Public API ──────────────────────────────────────────────────────────
+
+from .crypto import (
+    KEY_ROTATION_WINDOW_DAYS,
+    create_or_rotate_key_record,
+    decrypt,
+    encrypt,
+    generate_mlkem_keypair,
+    get_mlkem_public_key_bytes,
+    load_mlkem_public_key,
+    mlkem_private_key_from_hex,
+    mlkem_private_key_to_hex,
+    mlkem_public_key_from_json,
+    mlkem_public_key_to_json,
+)
+from .msgpack_utils import (
+    MSGPACK_DEFAULT_MAX_SIZE,
+    MSGPACK_MAX_ARRAY_LEN,
+    MSGPACK_MAX_BIN_LEN,
+    MSGPACK_MAX_EXT_LEN,
+    MSGPACK_MAX_MAP_LEN,
+    MSGPACK_MAX_STR_LEN,
+    msgpack_decode,
+    msgpack_encode,
+    validate_msgpack_size,
+)
+
+__all__ = [
+    # Key management
+    "KEY_ROTATION_WINDOW_DAYS",
+    "create_or_rotate_key_record",
+    "generate_mlkem_keypair",
+    "get_mlkem_public_key_bytes",
+    "load_mlkem_public_key",
+    "mlkem_private_key_from_hex",
+    "mlkem_private_key_to_hex",
+    "mlkem_public_key_from_json",
+    "mlkem_public_key_to_json",
+    # Encryption / decryption
+    "encrypt",
+    "decrypt",
+    # Msgpack utilities
+    "MSGPACK_DEFAULT_MAX_SIZE",
+    "MSGPACK_MAX_ARRAY_LEN",
+    "MSGPACK_MAX_BIN_LEN",
+    "MSGPACK_MAX_EXT_LEN",
+    "MSGPACK_MAX_MAP_LEN",
+    "MSGPACK_MAX_STR_LEN",
+    "msgpack_decode",
+    "msgpack_encode",
+    "validate_msgpack_size",
+]

iqcc_shared/crypto.py

@@ -0,0 +1,582 @@
+"""Cryptographic core: key management, path traversal, and symmetric encryption.
+
+Implements:
+  • ML-KEM-768 key encapsulation (post-quantum)
+  • AES-256-GCM symmetric payload encryption
+  • Dot-notation path resolver with wildcard support
+  • Hybrid encrypt / decrypt round-trip
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import uuid
+from datetime import UTC, datetime, timedelta
+from typing import Any
+from cryptography.hazmat.primitives.asymmetric import mlkem
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from .msgpack_utils import (
+    MSGPACK_DEFAULT_MAX_SIZE,
+    msgpack_decode,
+    msgpack_encode,
+    validate_msgpack_size,
+)
+
+# ── Constants ──────────────────────────────────────────────────────────────
+
+KEY_ROTATION_WINDOW_DAYS: int = 30
+WIRE_FORMAT_VERSION: str = "1.0"
+AES_KEY_SIZE: int = 32  # AES-256
+GCM_NONCE_SIZE: int = 12  # 96-bit recommended
+
+
+# ── ML-KEM-768 helpers ──────────────────────────────────────────────────
+
+
+def generate_mlkem_keypair() -> tuple[
+    mlkem.MLKEM768PrivateKey, mlkem.MLKEM768PublicKey
+]:
+    """Generate a fresh ML-KEM-768 key pair.
+
+    Returns:
+        A tuple of (private_key, public_key).
+    """
+    private_key = mlkem.MLKEM768PrivateKey.generate()
+    public_key = private_key.public_key()
+    return private_key, public_key
+
+
+def get_mlkem_public_key_bytes(public_key: mlkem.MLKEM768PublicKey) -> bytes:
+    """Serialize an ML-KEM-768 public key to raw bytes.
+
+    Args:
+        public_key: The ML-KEM-768 public key to serialize.
+
+    Returns:
+        The raw byte representation of the public key.
+    """
+    return public_key.public_bytes_raw()
+
+
+def load_mlkem_public_key(raw_bytes: bytes) -> mlkem.MLKEM768PublicKey:
+    """Deserialize an ML-KEM-768 public key from raw bytes.
+
+    Args:
+        raw_bytes: The raw byte representation of an ML-KEM-768 public key.
+
+    Returns:
+        The reconstructed ML-KEM-768 public key object.
+    """
+    return mlkem.MLKEM768PublicKey.from_public_bytes(raw_bytes)
+
+
+def mlkem_public_key_to_json(public_key: mlkem.MLKEM768PublicKey) -> str:
+    """Serialize an ML-KEM-768 public key to a JSON-encoded string.
+
+    The JSON payload contains ``format`` and ``key_hex`` (hex-encoded raw
+    bytes) so that public keys can be exchanged as plain JSON without any
+    msgpack coupling.
+
+    Args:
+        public_key: The ML-KEM-768 public key to serialize.
+
+    Returns:
+        A JSON string containing the public key data.
+    """
+    raw = public_key.public_bytes_raw()
+    payload = {"format": "ml-kem-768", "key_hex": raw.hex()}
+    return json.dumps(payload)
+
+
+def mlkem_public_key_from_json(json_string: str) -> mlkem.MLKEM768PublicKey:
+    """Deserialize an ML-KEM-768 public key from a JSON-encoded string.
+
+    Args:
+        json_string: A JSON string produced by ``mlkem_public_key_to_json``.
+
+    Returns:
+        The reconstructed ML-KEM-768 public key object.
+
+    Raises:
+        ValueError: If the JSON format is not ``ml-kem-768`` or the hex
+            payload is invalid.
+    """
+    payload = json.loads(json_string)
+    if payload.get("format") != "ml-kem-768":
+        raise ValueError(f"Unsupported key format in JSON: {payload.get('format')!r}")
+    raw = bytes.fromhex(payload["key_hex"])
+    return mlkem.MLKEM768PublicKey.from_public_bytes(raw)
+
+
+def mlkem_private_key_to_hex(private_key: mlkem.MLKEM768PrivateKey) -> str:
+    """Serialize an ML-KEM-768 private key to a hex-encoded string.
+
+    The hex string is safe for storage in Kubernetes secrets or other
+    string-compatible secret stores.
+
+    Args:
+        private_key: The ML-KEM-768 private key to serialize.
+
+    Returns:
+        A hex-encoded string of the raw private key bytes (64 bytes → 128
+        hex characters).
+    """
+    return private_key.private_bytes_raw().hex()
+
+
+def mlkem_private_key_from_hex(hex_string: str) -> mlkem.MLKEM768PrivateKey:
+    """Deserialize an ML-KEM-768 private key from a hex-encoded string.
+
+    Args:
+        hex_string: A hex-encoded string produced by ``mlkem_private_key_to_hex``.
+
+    Returns:
+        The reconstructed ML-KEM-768 private key object.
+
+    Raises:
+        ValueError: If the hex string is invalid.
+    """
+    return mlkem.MLKEM768PrivateKey.from_seed_bytes(bytes.fromhex(hex_string))
+
+
+# ── Key Record Creation & Rotation ───────────────────────────────────────
+
+
+def _build_key_entry(
+    public_key: mlkem.MLKEM768PublicKey,
+    expires_at: datetime,
+) -> dict:
+    """Build a key entry dict with ``public_key`` stored as a JSON string.
+
+    Args:
+        public_key: The ML-KEM-768 public key for this entry.
+        expires_at: The expiry datetime of the key.
+
+    Returns:
+        A dict with ``key_id``, ``public_key``, ``public_key_format``,
+        and ``expires_at``.
+    """
+    return {
+        "key_id": str(uuid.uuid4()),
+        "public_key": mlkem_public_key_to_json(public_key),
+        "public_key_format": "ml-kem-768",
+        "expires_at": expires_at.isoformat(),
+    }
+
+
+def create_or_rotate_key_record(
+    existing_record: dict | None = None,
+    validity_days: int = 180,
+    overlap_days: int = 30,
+) -> tuple[dict, str | None]:
+    """Create a fresh key record or rotate an existing one.
+
+    If *existing_record* is ``None`` a brand-new record is generated.
+    If the ``current`` key expires within ``KEY_ROTATION_WINDOW_DAYS``
+    a rotation is triggered: ``current → previous``, new key becomes
+    ``current``.
+
+    Args:
+        existing_record: Previously stored key record (from storage).
+            Pass ``None`` to create a fresh record.
+        validity_days: How many days the new key is valid from creation.
+        overlap_days: How many days the previous key remains valid
+            after rotation.
+
+    Returns:
+        A tuple of (key_record, private_key_hex). ``key_record`` is the
+        fully-formed dict ready for publishing. ``private_key_hex`` is a
+        hex-encoded string of the ML-KEM-768 private key corresponding to
+        the new ``current`` public key, suitable for storage in Kubernetes
+        secrets. It is ``None`` if no new key was generated
+        (i.e. the existing record was still valid and returned as-is).
+    """
+    now = datetime.now(UTC)
+
+    if existing_record is None:
+        priv, pub = generate_mlkem_keypair()
+        expires = now + timedelta(days=validity_days)
+        return {
+            "current": _build_key_entry(pub, expires),
+            "previous": None,
+            "rotation_policy": "auto",
+            "updated_at": now.isoformat(),
+        }, mlkem_private_key_to_hex(priv)
+
+    current_expiry = datetime.fromisoformat(
+        existing_record["current"]["expires_at"],
+    )
+    needs_rotation = (current_expiry - now).days <= KEY_ROTATION_WINDOW_DAYS
+
+    if not needs_rotation:
+        return existing_record, None
+
+    # ── Rotate ───────────────────────────────────────────────────
+    priv, pub = generate_mlkem_keypair()
+    new_expires = now + timedelta(days=validity_days)
+
+    old_current = dict(existing_record["current"])
+    old_current["expires_at"] = (now + timedelta(days=overlap_days)).isoformat()
+
+    return {
+        "current": _build_key_entry(pub, new_expires),
+        "previous": old_current,
+        "rotation_policy": "auto",
+        "updated_at": now.isoformat(),
+    }, mlkem_private_key_to_hex(priv)
+
+
+# ── Path Traversal ───────────────────────────────────────────────────────
+
+
+def _path_segments(path: str) -> list[str]:
+    """Split a dot-notation path into segments.
+
+    Args:
+        path: A dot-separated path string (e.g. ``auth.token``).
+
+    Returns:
+        A list of path segment strings.
+    """
+    return path.split(".")
+
+
+def _resolve_path_values(
+    obj: Any,
+    paths: list[str],
+    _prefix: list[str] | None = None,
+) -> list[tuple[Any, str]]:
+    """Recursively find all leaf values matching any entry in *paths*.
+
+    Supports ``.*`` wildcard at the end of a path segment to match all
+    children at that level.
+
+    Args:
+        obj: The object (dict) to traverse.
+        paths: List of dot-notation path strings to match.
+        _prefix: Internal accumulator for the current path prefix.
+
+    Returns:
+        A list of ``(parent_container, key)`` tuples pointing to the
+        values that should be encrypted/decrypted.
+    """
+    if _prefix is None:
+        _prefix = []
+
+    matches: list[tuple[Any, str]] = []
+
+    if not isinstance(obj, dict):
+        return matches
+
+    for key in obj:
+        current_path = _prefix + [key]
+        current_value = obj[key]
+
+        # Check if current path matches any of the target paths
+        for target_path in paths:
+            segs = _path_segments(target_path)
+
+            # Case 1: exact match (path has same number of segments)
+            if len(segs) == len(current_path):
+                if _segments_match(segs, current_path):
+                    matches.append((obj, key))
+                continue
+
+            # Case 2: target path is shorter (may have wildcard or is ancestor)
+            if len(segs) < len(current_path):
+                # Check if segments match (including wildcards)
+                if _segments_match(segs, current_path):
+                    if current_value and isinstance(current_value, dict):
+                        # Target might go deeper — recurse
+                        sub_matches = _resolve_path_values(
+                            current_value,
+                            paths,
+                            current_path,
+                        )
+                        if sub_matches:
+                            matches.extend(sub_matches)
+                        elif segs[-1] == "*":
+                            # Wildcard at end: match all leaves
+                            _collect_all_leaf_keys(current_value, matches)
+                    elif current_value and isinstance(current_value, list):
+                        _match_in_list(
+                            current_value, segs, len(current_path), paths, matches
+                        )
+                continue
+
+            # Case 3: target path is longer — this value must be a dict to descend
+            if len(segs) > len(current_path):
+                if _segments_match(segs[: len(current_path)], current_path):
+                    if isinstance(current_value, dict):
+                        sub = _resolve_path_values(current_value, paths, current_path)
+                        matches.extend(sub)
+
+    return matches
+
+
+def _segments_match(pattern_segs: list[str], actual_segs: list[str]) -> bool:
+    """Check if pattern segments match actual segments.
+
+    Supports ``*`` wildcard in any pattern position.
+
+    Args:
+        pattern_segs: List of pattern segments (may contain ``*``).
+        actual_segs: List of actual path segments to check.
+
+    Returns:
+        ``True`` if all segments match (wildcards match anything).
+    """
+    if len(pattern_segs) != len(actual_segs):
+        return False
+    for p, a in zip(pattern_segs, actual_segs):
+        if p != "*" and p != a:
+            return False
+    return True
+
+
+def _collect_all_leaf_keys(
+    obj: Any,
+    matches: list[tuple[Any, str]],
+    _parent: Any | None = None,
+    _key: str | None = None,
+) -> None:
+    """Collect all leaf (non-dict) keys under *obj* into *matches*.
+
+    Args:
+        obj: The dict to collect leaves from.
+        matches: List to append ``(parent, key)`` tuples into.
+        _parent: Internal parent reference for nested traversal.
+        _key: Internal key name for nested traversal.
+    """
+    if not isinstance(obj, dict):
+        return
+    for key in obj:
+        value = obj[key]
+        if isinstance(value, dict) and value:
+            _collect_all_leaf_keys(value, matches, obj, key)
+        else:
+            matches.append((obj, key))
+
+
+def _match_in_list(
+    lst: list,
+    target_segs: list[str],
+    current_depth: int,
+    paths: list[str],
+    matches: list[tuple[Any, str]],
+) -> None:
+    """Match paths within list elements.
+
+    Args:
+        lst: The list to traverse.
+        target_segs: Pattern segments from the target path.
+        current_depth: Current nesting depth.
+        paths: Full list of target paths.
+        matches: List to append ``(parent, key)`` tuples into.
+    """
+    for i, item in enumerate(lst):
+        if isinstance(item, dict):
+            sub = _resolve_path_values(item, paths)
+            matches.extend(sub)
+
+
+# ── AES-256-GCM encryption / decryption ─────────────────────────────────
+
+
+def _encrypt_value(plaintext: Any, key: bytes) -> dict:
+    """Encrypt *plaintext* with AES-256-GCM.
+
+    The plaintext is msgpack-encoded before encryption.
+
+    Args:
+        plaintext: The value to encrypt (any msgpack-serializable type).
+        key: The 32-byte AES-256 encryption key.
+
+    Returns:
+        A dict with ``encrypted``, ``nonce``, and ``tag`` keys.
+    """
+    nonce = os.urandom(GCM_NONCE_SIZE)
+    ciphertext_and_tag = AESGCM(key).encrypt(nonce, msgpack_encode(plaintext), None)
+    # AESGCM appends 16-byte tag at the end
+    ciphertext = ciphertext_and_tag[:-16]
+    tag = ciphertext_and_tag[-16:]
+    return {
+        "encrypted": ciphertext,
+        "nonce": nonce,
+        "tag": tag,
+    }
+
+
+def _decrypt_value(token: dict, key: bytes) -> Any:
+    """Decrypt an AES-256-GCM encrypted token.
+
+    Args:
+        token: Dict with ``encrypted``, ``nonce``, and ``tag`` keys.
+        key: The 32-byte AES-256 encryption key.
+
+    Returns:
+        The original plaintext (msgpack-decoded).
+    """
+    ciphertext = token["encrypted"]
+    nonce = token["nonce"]
+    tag = token["tag"]
+    ciphertext_and_tag = ciphertext + tag
+    plaintext_bytes = AESGCM(key).decrypt(nonce, ciphertext_and_tag, None)
+    return msgpack_decode(plaintext_bytes)
+
+
+# ── Public API: encrypt ──────────────────────────────────────────────────
+
+
+def encrypt(
+    payload: dict,
+    paths: list[str],
+    target_public_key: mlkem.MLKEM768PublicKey | None = None,
+    target_key_id: str = "",
+    session_key: bytes | None = None,
+) -> tuple[bytes, bytes]:
+    """Encrypt selected fields of *payload*.
+
+    Process:
+    1. Generate or use provided AES-256-GCM session key
+    2. Resolve matching paths and encrypt those values
+    3. Optionally encapsulate session key with ML-KEM-768
+    4. Build message dict with metadata + modified payload
+    5. Serialize to msgpack
+
+    Args:
+        payload: The dict containing data to encrypt.
+        paths: Dot-notation paths (supports ``.*`` wildcards) indicating
+            which fields to encrypt.
+        target_public_key: ML-KEM-768 public key for session key
+            encapsulation. Pass ``None`` when the receiver already holds
+            the session key (e.g. worker response path).
+        target_key_id: Identifier of the target public key used.
+            Ignored when ``target_public_key`` is ``None``.
+        session_key: Pre-generated AES-256-GCM session key to reuse.
+            When provided, it overrides any key from encapsulation.
+
+    Returns:
+        A tuple of ``(message_bytes, session_key)``. ``message_bytes`` is
+        the final msgpack-serialized ``bytes`` ready for transmission.
+        ``session_key`` is the 32-byte AES key used for encryption,
+        useful when the caller needs to store it for a later symmetric
+        reply (e.g. worker response path).
+    """
+    # 1. Resolve session key
+    encapsulated: bytes | None = None
+    if session_key is not None:
+        # Caller provided the key directly
+        resolved_session_key = session_key
+    elif target_public_key is not None:
+        # Encapsulate with target public key
+        resolved_session_key, encapsulated = target_public_key.encapsulate()
+    else:
+        # No encapsulation — generate a fresh key
+        resolved_session_key = os.urandom(AES_KEY_SIZE)
+
+    # 2. Deep-copy payload and encrypt matched values
+    encrypted_payload = copy.deepcopy(payload)
+    matches = _resolve_path_values(encrypted_payload, paths)
+    for container, key in matches:
+        container[key] = _encrypt_value(container[key], resolved_session_key)
+
+    # 3. Build metadata
+    metadata: dict = {
+        "encryption_metadata": {
+            "version": WIRE_FORMAT_VERSION,
+            "payload_encryption_algorithm": "AES-256-GCM",
+            "encrypted_paths": paths,
+            "timestamp": datetime.now(UTC).isoformat(),
+        },
+        "payload": encrypted_payload,
+    }
+
+    # Add encapsulation fields only when applicable
+    if encapsulated is not None:
+        metadata["encryption_metadata"]["key_encapsulation_algorithm"] = "ML-KEM-768"
+        metadata["encryption_metadata"]["target_public_key_id"] = target_key_id
+        metadata["encryption_metadata"]["encapsulated_session_key"] = encapsulated
+
+    return msgpack_encode(metadata), resolved_session_key
+
+
+# ── Public API: decrypt ──────────────────────────────────────────────────
+
+
+def decrypt(
+    message_bytes: bytes,
+    paths: list[str],
+    server_private_key: mlkem.MLKEM768PrivateKey | str | None = None,
+    session_key: bytes | None = None,
+    max_msgpack_len: int = MSGPACK_DEFAULT_MAX_SIZE,
+) -> tuple[dict, bytes]:
+    """Decrypt selected fields of a message.
+
+    Process:
+    1. Validate message size
+    2. Deserialize with strict limits
+    3. Resolve session key (decapsulate or use directly)
+    4. Decrypt matched values in the payload
+
+    Args:
+        message_bytes: Raw msgpack-encoded message from ``encrypt``.
+        paths: Same path list used during encryption.
+        server_private_key: ML-KEM-768 private key for decapsulating
+            the session key. Accepts either an ``MLKEM768PrivateKey``
+            object or a hex-encoded string (as returned by
+            ``create_or_rotate_key_record``). Required when decrypting
+            messages that contain ``encapsulated_session_key``.
+        session_key: Pre-resolved AES session key. Used when the message
+            has no encapsulation (e.g. worker response path) or to bypass
+            decapsulation entirely.
+        max_msgpack_len: Maximum allowed message size in bytes
+            (default 10 MiB).
+
+    Returns:
+        A tuple of (decrypted payload dict, 32-byte AES session key).
+
+    Raises:
+        ValueError: If the message has no encapsulation and no ``session_key``
+            is provided, or if the message size exceeds ``max_msgpack_len``.
+    """
+    # 1. Validate size
+    validate_msgpack_size(message_bytes, max_msgpack_len)
+
+    # 2. Decode
+    message = msgpack_decode(message_bytes)
+    metadata = message["encryption_metadata"]
+
+    # 3. Resolve session key
+    if session_key is not None:
+        resolved_key = session_key
+    elif "encapsulated_session_key" in metadata:
+        # Message contains encapsulation — decapsulate
+        if server_private_key is None:
+            raise ValueError(
+                "Message contains encapsulated session key but no "
+                "server_private_key was provided",
+            )
+        if isinstance(server_private_key, str):
+            server_private_key = mlkem_private_key_from_hex(server_private_key)
+        encapsulated = metadata["encapsulated_session_key"]
+        resolved_key = server_private_key.decapsulate(encapsulated)
+    else:
+        raise ValueError(
+            "Message has no encapsulated session key and no session_key "
+            "was provided. The receiver must provide the session_key "
+            "explicitly for symmetric-only messages.",
+        )
+
+    # 4. Decrypt matched values
+    payload = message["payload"]
+    matches = _resolve_path_values(payload, paths)
+    for container, key in matches:
+        token = container[key]
+        if isinstance(token, dict) and "encrypted" in token:
+            container[key] = _decrypt_value(token, resolved_key)
+
+    return payload, resolved_key

iqcc_shared/msgpack_utils.py

@@ -0,0 +1,99 @@
+"""msgpack serialization helpers with strict security hardening.
+
+All public decode entry points enforce strict mode to prevent
+memory exhaustion and type confusion attacks.
+"""
+
+from __future__ import annotations
+
+import msgpack
+
+# ── Default security limits ────────────────────────────────────────────
+MSGPACK_MAX_STR_LEN: int = 20 * 1024 * 1024  # 20 MiB
+MSGPACK_MAX_BIN_LEN: int = 20 * 1024 * 1024  # 20 MiB
+MSGPACK_MAX_ARRAY_LEN: int = 500_000
+MSGPACK_MAX_MAP_LEN: int = 100_000
+MSGPACK_MAX_EXT_LEN: int = 1_000
+MSGPACK_DEFAULT_MAX_SIZE: int = 20 * 1024 * 1024  # 20 MiB
+
+# ── Pre-built kwargs dicts ─────────────────────────────────────────────
+DECODE_KWARGS: dict = {
+    "raw": False,
+    "strict_map_key": True,
+    "max_str_len": MSGPACK_MAX_STR_LEN,
+    "max_bin_len": MSGPACK_MAX_BIN_LEN,
+    "max_array_len": MSGPACK_MAX_ARRAY_LEN,
+    "max_map_len": MSGPACK_MAX_MAP_LEN,
+    "max_ext_len": MSGPACK_MAX_EXT_LEN,
+}
+
+ENCODE_KWARGS: dict = {
+    "use_bin_type": True,
+}
+
+
+# ── Public helpers ─────────────────────────────────────────────────────
+
+
+def msgpack_encode(obj: object, **kwargs) -> bytes:
+    """Encode *obj* to msgpack bytes.
+
+    Extra keyword arguments override ``ENCODE_KWARGS`` defaults.
+
+    Args:
+        obj: The object to encode.
+        **kwargs: Additional keyword arguments passed to ``msgpack.packb``.
+
+    Returns:
+        The msgpack-encoded bytes.
+    """
+    merged = {**ENCODE_KWARGS, **kwargs}
+    return msgpack.packb(obj, **merged)
+
+
+def msgpack_decode(
+    data: bytes,
+    **decode_overrides,
+) -> object:
+    """Decode *data* from msgpack bytes with strict security limits.
+
+    Extra keyword arguments override ``DECODE_KWARGS`` defaults
+    (e.g. to tighten *max_str_len* further).
+
+    Args:
+        data: The raw msgpack bytes to decode.
+        **decode_overrides: Additional keyword arguments passed to
+            ``msgpack.unpackb``.
+
+    Returns:
+        The decoded Python object.
+    """
+    merged = {**DECODE_KWARGS, **decode_overrides}
+    return msgpack.unpackb(data, **merged)
+
+
+def validate_msgpack_size(
+    data: bytes,
+    max_size: int = MSGPACK_DEFAULT_MAX_SIZE,
+) -> bool:
+    """Validate that raw msgpack bytes do not exceed *max_size*.
+
+    Args:
+        data: The raw msgpack bytes to validate.
+        max_size: Maximum allowed size in bytes (default 20 MiB).
+
+    Returns:
+        ``True`` if the data is within the size limit.
+
+    Raises:
+        ValueError: If the data is empty or exceeds *max_size*.
+    """
+    if not data:
+        raise ValueError("msgpack data is empty")
+    size = len(data)
+    if size > max_size:
+        raise ValueError(
+            f"msgpack payload size ({size} bytes) exceeds maximum "
+            f"allowed size ({max_size} bytes)"
+        )
+    return True

iqcc_shared-0.1.0.dist-info/METADATA

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: iqcc-shared
+Version: 0.1.0
+Summary: Hybrid cryptographic utilities: ML-KEM-768 key encapsulation, ML-DSA-65 signing, AES-256-GCM payload encryption, and msgpack serialization
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=48.0.0
+Requires-Dist: msgpack>=1.0.8

iqcc_shared-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+iqcc_shared/__init__.py,sha256=b2YhM_SAITAGupJ_oGH7OrY70mSdAndPZd3eQlR5kNU,1952
+iqcc_shared/crypto.py,sha256=5KFmHm-ghlvnXJ4iJnUa-1IbnnBdSfkrWdbAS5UXXnE,20623
+iqcc_shared/msgpack_utils.py,sha256=B0oJlnnLqK3H0xJ1Y7T1ePwLXwSHZjgEEq6gy2S6cwo,3062
+iqcc_shared-0.1.0.dist-info/METADATA,sha256=30PVSZ4jhWvbP-_vSDU2zqupi4GwUDokw-0gySTZQcw,293
+iqcc_shared-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+iqcc_shared-0.1.0.dist-info/RECORD,,

iqcc_shared-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any