km-keybind 1.0.0__py3-none-any.whl

keybind/__init__.py

@@ -0,0 +1,19 @@
+# Copyright 2026 Pravanjan Roy
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .keybind import Keybind
+
+__all__ = ["Keybind"]
+
+

keybind/chunker.py

@@ -0,0 +1,30 @@
+# Copyright 2026 Pravanjan Roy
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+
+class ChunkManager:
+
+    def __init__(self, chunk_size: int = 1024 * 1024) -> None:
+        self.chunk_size = chunk_size
+
+    def split(self, payload: bytes) -> list[bytes]:
+        if payload is None:
+            return []
+        if len(payload) == 0:
+            return [b""]
+        return [payload[i : i + self.chunk_size] for i in range(0, len(payload), self.chunk_size)]
+
+

keybind/compressor.py

@@ -0,0 +1,41 @@
+# Copyright 2026 Pravanjan Roy
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import zstandard as zstd
+
+from .exceptions import CompressionError, raise_from
+from .interfaces import Compressor
+
+
+class ZstdCompressor(Compressor):
+
+    def __init__(self, level: int = 3) -> None:
+        self._compressor = zstd.ZstdCompressor(level=level)
+        self._decompressor = zstd.ZstdDecompressor()
+
+    def compress(self, payload: bytes) -> bytes:
+        try:
+            return self._compressor.compress(payload)
+        except Exception as exc:
+            raise_from(exc, CompressionError, "Compression failed")
+
+    def decompress(self, payload: bytes) -> bytes:
+        try:
+            return self._decompressor.decompress(payload)
+        except Exception as exc:
+            raise_from(exc, CompressionError, "Decompression failed")
+
+

keybind/config.py

@@ -0,0 +1,42 @@
+# Copyright 2026 Pravanjan Roy
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class KeybindConfig:
+
+    version: str = "SC1"
+    chunk_size: int = 8 * 1024 * 1024
+    compression_threshold: int = 256
+    compression_level: int = 3
+    stream_block_size: int = 64 * 1024
+    enable_compression: bool = True
+    enable_signature: bool = False
+    purpose: str = "keybind"
+    hash_algorithm: str = "blake3"
+    nonce_size: int = 24
+    tag_size: int = 16
+    max_token_size: int = 8 * 1024 * 1024 * 1024
+    max_chain_depth: int = 128
+    default_expiration_seconds: int | None = None
+    default_issued_at: bool = True
+
+    def clone(self) -> "KeybindConfig":
+        return KeybindConfig(**self.__dict__)
+
+

keybind/constants.py

@@ -0,0 +1,24 @@
+# Copyright 2026 Pravanjan Roy
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from typing import Final
+
+MAGIC: Final[bytes] = b"KB1"
+DEFAULT_PURPOSE: Final[str] = "keybind"
+DEFAULT_VERSION: Final[str] = "KB1"
+HEADER_VERSION: Final[int] = 1
+
+

keybind/crypto.py

@@ -0,0 +1,71 @@
+# Copyright 2026 Pravanjan Roy
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from .exceptions import CryptoError, raise_from
+
+try:
+    from cryptography.hazmat.primitives.ciphers.aead import XChaCha20Poly1305 as _CryptoXChaCha20Poly1305
+except ImportError:  
+    _CryptoXChaCha20Poly1305 = None
+
+try:
+    from nacl.bindings import (
+        crypto_aead_xchacha20poly1305_ietf_decrypt as _lib_decrypt,
+        crypto_aead_xchacha20poly1305_ietf_encrypt as _lib_encrypt,
+    )
+except ImportError:  
+    _lib_encrypt = None
+    _lib_decrypt = None
+
+
+class Encryptor:
+    def __init__(self, key: bytes) -> None:
+        if len(key) != 32:
+            raise CryptoError("Key must be 32 bytes")
+        self._key = key
+        self._cipher = _CryptoXChaCha20Poly1305(key) if _CryptoXChaCha20Poly1305 is not None else None
+
+    def encrypt(self, plaintext: bytes, nonce: bytes) -> bytes:
+        if len(nonce) != 24:
+            raise CryptoError("Nonce must be 24 bytes")
+        if self._cipher is not None:
+            try:
+                return self._cipher.encrypt(nonce, plaintext, None)
+            except Exception as exc:
+                raise_from(exc, CryptoError, "Encryption failed")
+        if _lib_encrypt is None:
+            raise CryptoError("No XChaCha20-Poly1305 backend is available")
+        try:
+            return _lib_encrypt(plaintext, b"", nonce, self._key)
+        except Exception as exc:
+            raise_from(exc, CryptoError, "Encryption failed")
+
+    def decrypt(self, ciphertext: bytes, nonce: bytes) -> bytes:
+        if len(nonce) != 24:
+            raise CryptoError("Nonce must be 24 bytes")
+        if self._cipher is not None:
+            try:
+                return self._cipher.decrypt(nonce, ciphertext, None)
+            except Exception as exc:
+                raise_from(exc, CryptoError, "Decryption failed")
+        if _lib_decrypt is None:
+            raise CryptoError("No XChaCha20-Poly1305 backend is available")
+        try:
+            return _lib_decrypt(ciphertext, b"", nonce, self._key)
+        except Exception as exc:
+            raise_from(exc, CryptoError, "Decryption failed")
+
+

keybind/enums.py

@@ -0,0 +1,29 @@
+# Copyright 2026 Pravanjan Roy
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class CompressionMethod(str, Enum):
+    NONE = "none"
+    ZSTANDARD = "zstd"
+
+
+class HashAlgorithm(str, Enum):
+    BLAKE3 = "blake3"
+    SHA3_256 = "sha3_256"
+
+

keybind/exceptions.py

@@ -0,0 +1,79 @@
+# Copyright 2026 Pravanjan Roy
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+
+class KeybindError(Exception):
+    """Base class for all Keybind errors."""
+
+    def __init__(self, message: str = "Keybind operation failed") -> None:
+        super().__init__(message)
+
+
+class InvalidToken(KeybindError):
+    """Raised when a token has invalid structure or encoding."""
+
+
+class ExpiredToken(KeybindError):
+    """Raised when the token validity window has elapsed."""
+
+
+class TamperedToken(KeybindError):
+    """Raised when authentication or integrity checks fail."""
+
+
+class IdentityMismatch(KeybindError):
+    """Raised when the identities used to decode do not match the token."""
+
+
+class InvalidSignature(KeybindError):
+    """Raised when a signature cannot be verified."""
+
+
+class CompressionError(KeybindError):
+    """Raised when compression or decompression fails."""
+
+
+class SerializationError(KeybindError):
+    """Raised when serialization or deserialization fails."""
+
+
+class ChunkError(KeybindError):
+    """Raised when chunk parsing or reconstruction fails."""
+
+
+class MerkleError(KeybindError):
+    """Raised when Merkle verification fails."""
+
+
+class CryptoError(KeybindError):
+    """Raised when cryptographic operations fail."""
+
+
+class StorageError(KeybindError):
+    """Raised when persistence operations fail."""
+
+
+def raise_from(exc: Exception, error_cls: type[KeybindError], message: str | None = None) -> None:
+    if isinstance(exc, KeybindError) and isinstance(exc, error_cls):
+        raise exc
+    raise error_cls(message or "Keybind operation failed") from exc
+
+
+def ensure(condition: bool, error_cls: type[KeybindError], message: str) -> None:
+    if not condition:
+        raise error_cls(message)
+
+

keybind/hasher.py

@@ -0,0 +1,31 @@
+# Copyright 2026 Pravanjan Roy
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import hashlib
+
+import blake3
+
+
+class HashManager:
+    @staticmethod
+    def blake3_digest(data: bytes) -> str:
+        return blake3.blake3(data).hexdigest()
+
+    @staticmethod
+    def sha3_256_digest(data: bytes) -> str:
+        return hashlib.sha3_256(data).hexdigest()
+
+

keybind/hkdf.py

@@ -0,0 +1,34 @@
+# Copyright 2026 Pravanjan Roy
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+
+class KeyDeriver:
+    @staticmethod
+    def derive_key(
+        master_key: bytes,
+        primary_identity: str,
+        secondary_identity: str,
+        version: str,
+        purpose: str = "keybind",
+    ) -> bytes:
+        info = f"{version}:{purpose}:{primary_identity}:{secondary_identity}".encode("utf-8")
+        hkdf = HKDF(algorithm=hashes.SHA256(), length=32, salt=b"keybind", info=info)
+        return hkdf.derive(master_key)
+
+

keybind/identities.py

@@ -0,0 +1,23 @@
+# Copyright 2026 Pravanjan Roy
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+
+class IdentityManager:
+    @staticmethod
+    def normalize(value: str) -> str:
+        return value.strip().lower()
+
+

keybind/interfaces.py

@@ -0,0 +1,27 @@
+# Copyright 2026 Pravanjan Roy
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class Compressor(ABC):
+    @abstractmethod
+    def compress(self, payload: bytes) -> bytes:
+        raise NotImplementedError
+
+    @abstractmethod
+    def decompress(self, payload: bytes) -> bytes:
+        raise NotImplementedError