klickd 3.0.0__py3-none-any.whl

klickd/__init__.py

@@ -0,0 +1,35 @@
+# klickd — Official Python library for .klickd portable AI context files
+# SPDX-License-Identifier: CC0-1.0
+#
+# One soul. Any model. Any body.
+#
+# Repository: https://github.com/Davincc77/klickdskill
+# DOI:        https://doi.org/10.5281/zenodo.20262530
+
+from .decode import load_klickd
+from .encode import save_klickd
+from .errors import KlickdError, KlickdErrorCode, HTTP_STATUS
+from ._types import (
+    KlickdPayload,
+    KlickdEnvelope,
+    KlickdMemoryEntry,
+    KlickdIdentity,
+    KlickdContext,
+    KlickdKnowledge,
+)
+
+__version__ = "3.0.0"
+__all__ = [
+    "load_klickd",
+    "save_klickd",
+    "KlickdError",
+    "KlickdErrorCode",
+    "HTTP_STATUS",
+    "KlickdPayload",
+    "KlickdEnvelope",
+    "KlickdMemoryEntry",
+    "KlickdIdentity",
+    "KlickdContext",
+    "KlickdKnowledge",
+    "__version__",
+]

klickd/_types.py

@@ -0,0 +1,84 @@
+# .klickd v3 — Python TypedDict definitions
+# SPDX-License-Identifier: CC0-1.0
+
+from __future__ import annotations
+
+from typing import Any, List, Literal, Optional
+from typing_extensions import TypedDict, Required
+
+
+class KlickdKdfArgon2idParams(TypedDict):
+    m: int
+    t: int
+    p: int
+
+
+class KlickdKdfArgon2id(TypedDict):
+    name: Literal["argon2id"]
+    params: KlickdKdfArgon2idParams
+    salt: str  # base64
+
+
+class KlickdKdfPbkdf2Params(TypedDict):
+    iterations: int
+
+
+class KlickdKdfPbkdf2(TypedDict):
+    name: Literal["pbkdf2-sha256"]
+    params: KlickdKdfPbkdf2Params
+    salt: str  # base64
+
+
+class KlickdCipher(TypedDict):
+    name: Literal["AES-256-GCM"]
+    iv: str  # base64
+
+
+class KlickdEnvelope(TypedDict, total=False):
+    klickd_version: Required[str]
+    encrypted: Required[bool]
+    domain: Required[str]
+    created_at: Required[str]       # RFC 3339 UTC Z
+    kdf: Required[dict]             # KlickdKdfArgon2id | KlickdKdfPbkdf2
+    cipher: Required[KlickdCipher]
+    ciphertext: Required[str]       # base64
+
+
+class KlickdMemoryEntry(TypedDict, total=False):
+    id: Required[str]               # UUID v4
+    ts: Required[str]               # RFC 3339 UTC Z
+    role: Required[str]             # user | assistant | system
+    content: Required[str]
+    modality: Required[str]         # text | image | audio | tool_call
+    tags: List[str]
+
+
+class KlickdIdentity(TypedDict, total=False):
+    name: str
+    language: str
+    timezone: str
+    communication_style: str
+
+
+class KlickdContext(TypedDict, total=False):
+    current_state: str
+    decisions_locked: List[str]
+    artifacts: List[Any]
+    summary: str
+
+
+class KlickdKnowledge(TypedDict, total=False):
+    mastered: List[str]
+    gaps: List[str]
+    next_steps: List[str]
+
+
+class KlickdPayload(TypedDict, total=False):
+    payload_schema_version: Required[str]
+    domain_schema_version: Required[str]
+    identity: KlickdIdentity
+    agent_instructions: str
+    user_preferences: dict
+    context: KlickdContext
+    knowledge: KlickdKnowledge
+    memory: List[KlickdMemoryEntry]

klickd/decode.py

@@ -0,0 +1,181 @@
+# .klickd v3 — decode (load) implementation
+# SPDX-License-Identifier: CC0-1.0
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from typing import Any
+
+import jcs
+from argon2.low_level import hash_secret_raw, Type
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from .errors import KlickdError, KlickdErrorCode
+
+SUPPORTED_MAJOR = 3
+REQUIRED_ENVELOPE_FIELDS = frozenset(
+    ["klickd_version", "encrypted", "domain", "created_at", "kdf", "cipher", "ciphertext"]
+)
+
+
+def _b64_decode(s: str) -> bytes:
+    """RFC 4648 §4 standard padded base64 decode."""
+    return base64.b64decode(s)
+
+
+def _derive_key_argon2id(passphrase: str, salt: bytes, m: int, t: int, p: int) -> bytes:
+    return hash_secret_raw(
+        secret=passphrase.encode("utf-8"),
+        salt=salt,
+        time_cost=t,
+        memory_cost=m,
+        parallelism=p,
+        hash_len=32,
+        type=Type.ID,
+    )
+
+
+def _derive_key_pbkdf2(passphrase: str, salt: bytes, iterations: int) -> bytes:
+    return hashlib.pbkdf2_hmac("sha256", passphrase.encode("utf-8"), salt, iterations, dklen=32)
+
+
+def load_klickd(
+    file_bytes: bytes,
+    passphrase: str | None = None,
+    legacy: bool = False,
+) -> dict[str, Any]:
+    """
+    Decrypt and parse a .klickd envelope.
+
+    Args:
+        file_bytes: Raw .klickd file content (UTF-8 JSON bytes).
+        passphrase: Decryption passphrase.
+        legacy:     Set ``True`` to allow legacy PBKDF2-SHA256/600k v2.x files.
+                    Default: ``False``.
+
+    Returns:
+        The decrypted payload as a dict (KlickdPayload-compatible).
+
+    Raises:
+        KlickdError: On any format, version, authentication, or schema error.
+    """
+    # Parse envelope JSON
+    try:
+        envelope: dict[str, Any] = json.loads(file_bytes.decode("utf-8"))
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise KlickdError(KlickdErrorCode.FORMAT, f"Invalid JSON envelope: {exc}") from exc
+
+    if not isinstance(envelope, dict):
+        raise KlickdError(KlickdErrorCode.FORMAT, "Envelope must be a JSON object.")
+
+    # Validate required fields
+    missing = REQUIRED_ENVELOPE_FIELDS - envelope.keys()
+    if missing:
+        raise KlickdError(
+            KlickdErrorCode.FORMAT,
+            f"Missing required envelope fields: {', '.join(sorted(missing))}",
+        )
+
+    # Check major version
+    try:
+        major = int(str(envelope["klickd_version"]).split(".")[0])
+    except (ValueError, IndexError) as exc:
+        raise KlickdError(
+            KlickdErrorCode.VERSION,
+            f"Cannot parse klickd_version: {envelope['klickd_version']}",
+        ) from exc
+
+    if major != SUPPORTED_MAJOR:
+        raise KlickdError(
+            KlickdErrorCode.VERSION,
+            f"Unsupported klickd_version major: {envelope['klickd_version']}. "
+            f"This library supports v{SUPPORTED_MAJOR}.x.",
+        )
+
+    # Reconstruct AAD: JCS over the 6 canonical fields
+    envelope_for_aad: dict[str, Any] = {
+        "klickd_version": envelope["klickd_version"],
+        "encrypted": envelope["encrypted"],
+        "domain": envelope["domain"],
+        "created_at": envelope["created_at"],
+        "kdf": envelope["kdf"],
+        "cipher": envelope["cipher"],
+    }
+    aad: bytes = jcs.canonicalize(envelope_for_aad)
+
+    # Require passphrase
+    if not passphrase:
+        raise KlickdError(
+            KlickdErrorCode.AUTH,
+            "A passphrase is required to decrypt this file.",
+        )
+
+    # Derive key
+    kdf = envelope["kdf"]
+    kdf_name: str = kdf.get("name", "")
+
+    if kdf_name == "argon2id":
+        try:
+            salt = _b64_decode(kdf["salt"])
+            params = kdf["params"]
+            key = _derive_key_argon2id(passphrase, salt, params["m"], params["t"], params["p"])
+        except (KeyError, TypeError) as exc:
+            raise KlickdError(KlickdErrorCode.FORMAT, f"Invalid Argon2id KDF params: {exc}") from exc
+
+    elif kdf_name == "pbkdf2-sha256":
+        if not legacy:
+            raise KlickdError(
+                KlickdErrorCode.KDF,
+                "Legacy PBKDF2 KDF detected. Set legacy=True to enable reading legacy v2.x files.",
+            )
+        try:
+            salt = _b64_decode(kdf["salt"])
+            iterations = kdf["params"]["iterations"]
+            key = _derive_key_pbkdf2(passphrase, salt, iterations)
+        except (KeyError, TypeError) as exc:
+            raise KlickdError(KlickdErrorCode.FORMAT, f"Invalid PBKDF2 KDF params: {exc}") from exc
+
+    else:
+        raise KlickdError(KlickdErrorCode.KDF, f"Unknown KDF: '{kdf_name}'.")
+
+    # Decode ciphertext (ciphertext || 16-byte GCM tag, per AESGCM convention)
+    try:
+        ciphertext_with_tag = _b64_decode(envelope["ciphertext"])
+    except Exception as exc:
+        raise KlickdError(KlickdErrorCode.FORMAT, f"Invalid ciphertext base64: {exc}") from exc
+
+    if len(ciphertext_with_tag) < 16:
+        raise KlickdError(KlickdErrorCode.FORMAT, "Ciphertext too short.")
+
+    # Decrypt AES-256-GCM
+    try:
+        iv = _b64_decode(envelope["cipher"]["iv"])
+    except (KeyError, Exception) as exc:
+        raise KlickdError(KlickdErrorCode.FORMAT, f"Invalid cipher IV: {exc}") from exc
+
+    try:
+        aesgcm = AESGCM(key)
+        plaintext = aesgcm.decrypt(iv, ciphertext_with_tag, aad)
+    except InvalidTag as exc:
+        raise KlickdError(
+            KlickdErrorCode.AUTH,
+            "Decryption failed: wrong passphrase or corrupted file.",
+        ) from exc
+
+    # Parse payload JSON
+    try:
+        payload: dict[str, Any] = json.loads(plaintext.decode("utf-8"))
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise KlickdError(KlickdErrorCode.FORMAT, f"Decrypted data is not valid JSON: {exc}") from exc
+
+    # Validate payload_schema_version
+    if not payload.get("payload_schema_version"):
+        raise KlickdError(
+            KlickdErrorCode.SCHEMA,
+            "Decrypted payload is missing payload_schema_version.",
+        )
+
+    return payload

klickd/encode.py

@@ -0,0 +1,116 @@
+# .klickd v3 — encode (save) implementation
+# SPDX-License-Identifier: CC0-1.0
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+from typing import Any
+
+import jcs
+from argon2.low_level import hash_secret_raw, Type
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from .errors import KlickdError, KlickdErrorCode
+
+KLICKD_VERSION = "3.0.0"
+DEFAULT_KDF_PARAMS = {"m": 65536, "t": 3, "p": 1}
+
+
+def _b64_encode(data: bytes) -> str:
+    """RFC 4648 §4 standard padded base64."""
+    return base64.b64encode(data).decode("ascii")
+
+
+def _derive_key_argon2id(passphrase: str, salt: bytes, m: int, t: int, p: int) -> bytes:
+    """Derive a 32-byte key using Argon2id."""
+    return hash_secret_raw(
+        secret=passphrase.encode("utf-8"),
+        salt=salt,
+        time_cost=t,
+        memory_cost=m,
+        parallelism=p,
+        hash_len=32,
+        type=Type.ID,
+    )
+
+
+def save_klickd(
+    payload: dict[str, Any],
+    passphrase: str,
+    domain: str = "education",
+    kdf_params: dict[str, int] | None = None,
+) -> bytes:
+    """
+    Encrypt a KlickdPayload dict and return a .klickd JSON envelope as UTF-8 bytes.
+
+    Args:
+        payload:    Dict conforming to KlickdPayload schema.
+                    Must include ``payload_schema_version``.
+        passphrase: Encryption passphrase (minimum 8 characters).
+        domain:     .klickd domain tag. Default: ``"education"``.
+        kdf_params: Argon2id parameter overrides.
+                    Defaults to ``{"m": 65536, "t": 3, "p": 1}``.
+
+    Returns:
+        UTF-8 bytes of the complete .klickd JSON envelope.
+
+    Raises:
+        KlickdError: On validation or cryptographic failure.
+    """
+    params = kdf_params or DEFAULT_KDF_PARAMS
+
+    # Validate passphrase
+    if not passphrase or len(passphrase) < 8:
+        raise KlickdError(KlickdErrorCode.WEAK_PASS, "Passphrase must be at least 8 characters.")
+
+    # Validate payload schema version
+    if not payload.get("payload_schema_version"):
+        raise KlickdError(KlickdErrorCode.SCHEMA, "payload_schema_version is required.")
+
+    # Generate fresh CSPRNG salt (16 bytes) and IV (12 bytes)
+    salt = os.urandom(16)
+    iv = os.urandom(12)
+
+    # Derive 32-byte key
+    key = _derive_key_argon2id(
+        passphrase, salt, params["m"], params["t"], params["p"]
+    )
+
+    # Build the 6-field envelope object for AAD (without ciphertext)
+    from datetime import datetime, timezone
+    created_at = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    envelope_for_aad: dict[str, Any] = {
+        "klickd_version": KLICKD_VERSION,
+        "encrypted": True,
+        "domain": domain,
+        "created_at": created_at,
+        "kdf": {
+            "name": "argon2id",
+            "params": {"m": params["m"], "t": params["t"], "p": params["p"]},
+            "salt": _b64_encode(salt),
+        },
+        "cipher": {
+            "name": "AES-256-GCM",
+            "iv": _b64_encode(iv),
+        },
+    }
+
+    # AAD = RFC 8785 JCS (JSON Canonicalization Scheme)
+    aad: bytes = jcs.canonicalize(envelope_for_aad)
+
+    # Encrypt payload JSON with AES-256-GCM
+    # cryptography's AESGCM appends the 16-byte tag to ciphertext
+    aesgcm = AESGCM(key)
+    plaintext = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+    ciphertext_with_tag = aesgcm.encrypt(iv, plaintext, aad)
+
+    # Build final envelope
+    envelope: dict[str, Any] = {
+        **envelope_for_aad,
+        "ciphertext": _b64_encode(ciphertext_with_tag),
+    }
+
+    return json.dumps(envelope, ensure_ascii=False, separators=(",", ":")).encode("utf-8")

klickd/errors.py

@@ -0,0 +1,32 @@
+# .klickd error definitions
+# SPDX-License-Identifier: CC0-1.0
+
+from enum import Enum
+
+
+class KlickdErrorCode(str, Enum):
+    AUTH = "KLICKD_E_AUTH"          # Wrong passphrase / GCM tag mismatch
+    VERSION = "KLICKD_E_VERSION"    # Unsupported klickd_version major
+    FORMAT = "KLICKD_E_FORMAT"      # Malformed envelope JSON / missing fields
+    KDF = "KLICKD_E_KDF"            # Unknown/unsupported KDF
+    WEAK_PASS = "KLICKD_E_WEAK_PASS"  # Passphrase < 8 characters
+    SCHEMA = "KLICKD_E_SCHEMA"      # Missing payload_schema_version
+
+
+HTTP_STATUS: dict[KlickdErrorCode, int] = {
+    KlickdErrorCode.AUTH: 401,
+    KlickdErrorCode.VERSION: 400,
+    KlickdErrorCode.FORMAT: 400,
+    KlickdErrorCode.KDF: 400,
+    KlickdErrorCode.WEAK_PASS: 422,
+    KlickdErrorCode.SCHEMA: 400,
+}
+
+
+class KlickdError(Exception):
+    """Raised for all .klickd format and cryptographic errors."""
+
+    def __init__(self, code: KlickdErrorCode, message: str) -> None:
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.http_status: int = HTTP_STATUS[code]

klickd-3.0.0.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: klickd
+Version: 3.0.0
+Summary: Official Python library for reading and writing .klickd portable AI context files
+Project-URL: Homepage, https://klickd.app
+Project-URL: Repository, https://github.com/Davincc77/klickdskill
+Project-URL: Documentation, https://github.com/Davincc77/klickdskill/blob/main/SPEC.md
+Author-email: "Vince C." <Luxlearn@pm.me>
+License: CC0-1.0
+Keywords: ai-context,encrypted,klickd,memory,portable
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: argon2-cffi>=23.1
+Requires-Dist: cryptography>=41.0
+Requires-Dist: jcs>=0.2
+Description-Content-Type: text/markdown
+
+# klickd
+
+Official Python library for reading and writing `.klickd` portable AI context files.
+
+**One soul. Any model. Any body.**
+
+[![PyPI version](https://img.shields.io/pypi/v/klickd)](https://pypi.org/project/klickd/)
+[![Python](https://img.shields.io/pypi/pyversions/klickd)](https://pypi.org/project/klickd/)
+[![License: CC0-1.0](https://img.shields.io/badge/License-CC0_1.0-lightgrey.svg)](https://creativecommons.org/publicdomain/zero/1.0/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20262530.svg)](https://doi.org/10.5281/zenodo.20262530)
+
+---
+
+## Install
+
+```bash
+pip install klickd
+```
+
+---
+
+## Quick start
+
+### Load (decrypt) a `.klickd` file
+
+```python
+from klickd import load_klickd
+
+with open("context.klickd", "rb") as f:
+    payload = load_klickd(f.read(), passphrase="my-passphrase")
+
+print(payload["identity"]["name"])
+print(payload["memory"])
+```
+
+### Save (encrypt) a `.klickd` file
+
+```python
+from klickd import save_klickd
+
+payload = {
+    "payload_schema_version": "3.0.0",
+    "domain_schema_version": "1.0.0",
+    "identity": {"name": "Alice", "language": "en", "timezone": "Europe/Luxembourg"},
+    "agent_instructions": "Be concise.",
+    "memory": [],
+}
+
+klickd_bytes = save_klickd(payload, passphrase="my-passphrase", domain="education")
+
+with open("context.klickd", "wb") as f:
+    f.write(klickd_bytes)
+```
+
+### Legacy v2.x files (PBKDF2)
+
+```python
+payload = load_klickd(file_bytes, passphrase="my-passphrase", legacy=True)
+```
+
+---
+
+## Cryptographic specification (v3.0)
+
+| Parameter     | Value                                   |
+|---------------|-----------------------------------------|
+| KDF (default) | Argon2id — m=65536, t=3, p=1           |
+| KDF (legacy)  | PBKDF2-SHA256 / 600 000 iterations      |
+| Cipher        | AES-256-GCM                             |
+| AAD           | RFC 8785 JCS over 6 canonical fields    |
+| Base64        | RFC 4648 §4 standard padded             |
+| Salt          | 16 bytes (CSPRNG)                       |
+| IV            | 12 bytes (CSPRNG)                       |
+
+---
+
+## Error codes
+
+| Code                  | HTTP | Meaning                                  |
+|-----------------------|------|------------------------------------------|
+| `KLICKD_E_AUTH`       | 401  | Wrong passphrase / GCM tag mismatch      |
+| `KLICKD_E_VERSION`    | 400  | Unsupported `klickd_version` major       |
+| `KLICKD_E_FORMAT`     | 400  | Malformed JSON envelope / missing fields |
+| `KLICKD_E_KDF`        | 400  | Unknown or unavailable KDF               |
+| `KLICKD_E_WEAK_PASS`  | 422  | Passphrase shorter than 8 characters     |
+| `KLICKD_E_SCHEMA`     | 400  | Missing `payload_schema_version`         |
+
+```python
+from klickd import KlickdError, KlickdErrorCode
+
+try:
+    payload = load_klickd(data, passphrase="wrong")
+except KlickdError as e:
+    print(e.code)         # KlickdErrorCode.AUTH
+    print(e.http_status)  # 401
+```
+
+---
+
+## Links
+
+- Specification: [SPEC.md](https://github.com/Davincc77/klickdskill/blob/main/SPEC.md)
+- Repository: [github.com/Davincc77/klickdskill](https://github.com/Davincc77/klickdskill)
+- DOI: [10.5281/zenodo.20262530](https://doi.org/10.5281/zenodo.20262530)
+- Homepage: [klickd.app](https://klickd.app)
+
+---
+
+## License
+
+[CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/) — Public Domain Dedication.  
+Author: Vince C. (Luxlearn, Luxembourg)

klickd-3.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+klickd/__init__.py,sha256=MDpYv_3ZzqKku92X8zTJZIp14FgH7dS8m1jbj9O7-js,818
+klickd/_types.py,sha256=mV7OKseFIdLNKATRjCfUzbAfYxG554dTWKNHfUxoeTU,2075
+klickd/decode.py,sha256=9yNNZVaRPUOdaNp0LEiw691Ou-tJzDO67y0ufSW19bs,6056
+klickd/encode.py,sha256=mwtqReq0aQeTs5UG_k38MgvngZCoHjUGvw4nGLWTITo,3619
+klickd/errors.py,sha256=BKHZRRA5aTbbE0MybNSkCVILp9ZifnkCkT4IOqzcCP8,1078
+klickd-3.0.0.dist-info/METADATA,sha256=youPc90jkDfzApHPGHJx3yetUxRSzBNkmABTsN12TyY,4508
+klickd-3.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+klickd-3.0.0.dist-info/RECORD,,

klickd-3.0.0.dist-info/WHEEL

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