klickd 3.0.0__tar.gz

klickd-3.0.0/.gitignore

@@ -0,0 +1,9 @@
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+
+# Node
+node_modules/
+dist/

klickd-3.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,112 @@
+# 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/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "klickd"
+version = "3.0.0"
+description = "Official Python library for reading and writing .klickd portable AI context files"
+readme = "README.md"
+license = {text = "CC0-1.0"}
+authors = [{name = "Vince C.", email = "Luxlearn@pm.me"}]
+keywords = ["klickd", "ai-context", "portable", "memory", "encrypted"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Security :: Cryptography",
+  "Topic :: Software Development :: Libraries",
+]
+requires-python = ">=3.9"
+dependencies = [
+  "cryptography>=41.0",
+  "argon2-cffi>=23.1",
+  "jcs>=0.2",
+]
+
+[project.urls]
+Homepage = "https://klickd.app"
+Repository = "https://github.com/Davincc77/klickdskill"
+Documentation = "https://github.com/Davincc77/klickdskill/blob/main/SPEC.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/klickd"]

klickd-3.0.0/src/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-3.0.0/src/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-3.0.0/src/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-3.0.0/src/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-3.0.0/src/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/tests/test_roundtrip.py

@@ -0,0 +1,134 @@
+# klickd — roundtrip test
+# SPDX-License-Identifier: CC0-1.0
+
+import json
+import pytest
+from klickd import load_klickd, save_klickd, KlickdError, KlickdErrorCode
+
+TEST_PAYLOAD = {
+    "payload_schema_version": "3.0.0",
+    "domain_schema_version": "1.0.0",
+    "identity": {
+        "name": "Test User",
+        "language": "en",
+        "timezone": "Europe/Luxembourg",
+    },
+    "agent_instructions": "Be concise and precise.",
+    "memory": [
+        {
+            "id": "00000000-0000-4000-a000-000000000001",
+            "ts": "2025-01-01T00:00:00Z",
+            "role": "user",
+            "content": "Hello from the test suite.",
+            "modality": "text",
+            "tags": ["test"],
+        }
+    ],
+}
+
+PASSPHRASE = "correct-horse-battery-staple"
+
+
+class TestRoundtrip:
+    def test_save_and_load(self):
+        """Encrypt and decrypt a payload successfully."""
+        envelope_bytes = save_klickd(TEST_PAYLOAD, PASSPHRASE, domain="education")
+
+        # Verify the envelope structure
+        envelope = json.loads(envelope_bytes)
+        assert envelope["klickd_version"] == "3.0.0"
+        assert envelope["encrypted"] is True
+        assert envelope["domain"] == "education"
+        assert envelope["kdf"]["name"] == "argon2id"
+        assert isinstance(envelope["ciphertext"], str)
+
+        # Decrypt and verify payload
+        payload = load_klickd(envelope_bytes, passphrase=PASSPHRASE)
+
+        assert payload["payload_schema_version"] == "3.0.0"
+        assert payload["domain_schema_version"] == "1.0.0"
+        assert payload["identity"]["name"] == "Test User"
+        assert payload["memory"][0]["content"] == "Hello from the test suite."
+
+    def test_wrong_passphrase(self):
+        """Wrong passphrase raises KLICKD_E_AUTH."""
+        envelope_bytes = save_klickd(TEST_PAYLOAD, PASSPHRASE)
+        with pytest.raises(KlickdError) as exc_info:
+            load_klickd(envelope_bytes, passphrase="wrong-passphrase")
+        assert exc_info.value.code == KlickdErrorCode.AUTH
+        assert exc_info.value.http_status == 401
+
+    def test_weak_passphrase(self):
+        """Passphrase < 8 characters raises KLICKD_E_WEAK_PASS."""
+        with pytest.raises(KlickdError) as exc_info:
+            save_klickd(TEST_PAYLOAD, "short")
+        assert exc_info.value.code == KlickdErrorCode.WEAK_PASS
+        assert exc_info.value.http_status == 422
+
+    def test_malformed_json(self):
+        """Non-JSON input raises KLICKD_E_FORMAT."""
+        with pytest.raises(KlickdError) as exc_info:
+            load_klickd(b"not-json", passphrase=PASSPHRASE)
+        assert exc_info.value.code == KlickdErrorCode.FORMAT
+
+    def test_missing_schema_version(self):
+        """Payload missing payload_schema_version raises KLICKD_E_SCHEMA."""
+        bad_payload = {"domain_schema_version": "1.0.0"}
+        with pytest.raises(KlickdError) as exc_info:
+            save_klickd(bad_payload, PASSPHRASE)
+        assert exc_info.value.code == KlickdErrorCode.SCHEMA
+
+    def test_legacy_kdf_requires_flag(self):
+        """PBKDF2 KDF envelope without legacy=True raises KLICKD_E_KDF."""
+        fake_envelope = json.dumps({
+            "klickd_version": "3.0.0",
+            "encrypted": True,
+            "domain": "education",
+            "created_at": "2025-01-01T00:00:00Z",
+            "kdf": {
+                "name": "pbkdf2-sha256",
+                "params": {"iterations": 600000},
+                "salt": "AAAAAAAAAAAAAAAAAAAAAA==",
+            },
+            "cipher": {"name": "AES-256-GCM", "iv": "AAAAAAAAAAAAAAAA"},
+            "ciphertext": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+        }).encode("utf-8")
+
+        with pytest.raises(KlickdError) as exc_info:
+            load_klickd(fake_envelope, passphrase=PASSPHRASE)
+        assert exc_info.value.code == KlickdErrorCode.KDF
+
+    def test_unsupported_version(self):
+        """A v99 envelope raises KLICKD_E_VERSION."""
+        fake_envelope = json.dumps({
+            "klickd_version": "99.0.0",
+            "encrypted": True,
+            "domain": "education",
+            "created_at": "2025-01-01T00:00:00Z",
+            "kdf": {"name": "argon2id", "params": {"m": 65536, "t": 3, "p": 1}, "salt": "AAAAAAAAAAAAAAAAAAAAAA=="},
+            "cipher": {"name": "AES-256-GCM", "iv": "AAAAAAAAAAAAAAAA"},
+            "ciphertext": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+        }).encode("utf-8")
+
+        with pytest.raises(KlickdError) as exc_info:
+            load_klickd(fake_envelope, passphrase=PASSPHRASE)
+        assert exc_info.value.code == KlickdErrorCode.VERSION
+
+    def test_each_save_produces_unique_ciphertext(self):
+        """Each call to save_klickd produces a fresh salt/IV (probabilistic encryption)."""
+        e1 = save_klickd(TEST_PAYLOAD, PASSPHRASE)
+        e2 = save_klickd(TEST_PAYLOAD, PASSPHRASE)
+        assert json.loads(e1)["kdf"]["salt"] != json.loads(e2)["kdf"]["salt"]
+        assert json.loads(e1)["cipher"]["iv"] != json.loads(e2)["cipher"]["iv"]
+        assert json.loads(e1)["ciphertext"] != json.loads(e2)["ciphertext"]
+
+    def test_custom_argon2id_params(self):
+        """Custom Argon2id params are stored in the envelope and round-trip correctly."""
+        custom_params = {"m": 32768, "t": 2, "p": 1}
+        envelope_bytes = save_klickd(TEST_PAYLOAD, PASSPHRASE, kdf_params=custom_params)
+        envelope = json.loads(envelope_bytes)
+        assert envelope["kdf"]["params"]["m"] == 32768
+        assert envelope["kdf"]["params"]["t"] == 2
+
+        payload = load_klickd(envelope_bytes, passphrase=PASSPHRASE)
+        assert payload["payload_schema_version"] == "3.0.0"