starfish-protocol 1.0.0__tar.gz

starfish_protocol-1.0.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: starfish-protocol
+Version: 1.0.0
+Summary: Shared protocol primitives for the Starfish sync protocol
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=41.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

starfish_protocol-1.0.0/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "starfish-protocol"
+version = "1.0.0"
+description = "Shared protocol primitives for the Starfish sync protocol"
+requires-python = ">=3.11"
+dependencies = ["cryptography>=41.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.21"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

starfish_protocol-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

starfish_protocol-1.0.0/starfish_protocol/__init__.py

@@ -0,0 +1,16 @@
+from starfish_protocol.hash import stable_stringify, compute_hash
+from starfish_protocol.merge import deep_merge
+from starfish_protocol.crypto import _derive_key, IV_BYTES, ENCRYPTED_KEY
+from starfish_protocol.types import Timestamps, PullResult, PushSuccess
+
+__all__ = [
+    "stable_stringify",
+    "compute_hash",
+    "deep_merge",
+    "_derive_key",
+    "IV_BYTES",
+    "ENCRYPTED_KEY",
+    "Timestamps",
+    "PullResult",
+    "PushSuccess",
+]

starfish_protocol-1.0.0/starfish_protocol/crypto.py

@@ -0,0 +1,19 @@
+"""Shared cryptographic primitives for the Starfish sync protocol."""
+
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+IV_BYTES = 12
+ENCRYPTED_KEY = "_encrypted"
+
+
+def _derive_key(secret: str, salt: str, info: bytes) -> bytes:
+    """Derive a 256-bit AES key from a secret and salt using HKDF(SHA-256)."""
+    hkdf = HKDF(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=salt.encode("utf-8"),
+        info=info,
+    )
+    return hkdf.derive(secret.encode("utf-8"))

starfish_protocol-1.0.0/starfish_protocol/hash.py

@@ -0,0 +1,34 @@
+"""Deterministic hashing — must produce identical output to the TS implementation."""
+
+
+import hashlib
+import json
+from typing import Any
+
+
+def stable_stringify(value: Any) -> str:
+    """Deterministic JSON serialization with sorted keys (recursive).
+
+    Must produce identical output to the server's stableStringify.
+    """
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, list):
+        return "[" + ",".join(stable_stringify(v) for v in value) + "]"
+    if isinstance(value, dict):
+        keys = sorted(value.keys())
+        pairs = [json.dumps(k, ensure_ascii=False) + ":" + stable_stringify(value[k]) for k in keys]
+        return "{" + ",".join(pairs) + "}"
+    return "null"
+
+
+def compute_hash(data: dict[str, Any]) -> str:
+    """Compute SHA-256 hex digest of the stable-stringified data."""
+    encoded = stable_stringify(data).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()

starfish_protocol-1.0.0/starfish_protocol/merge.py

@@ -0,0 +1,23 @@
+"""Document merge utilities for conflict resolution."""
+
+
+from typing import Any
+
+
+def deep_merge(local: dict[str, Any], remote: dict[str, Any]) -> dict[str, Any]:
+    """Remote-wins deep merge.
+
+    Recursively merges *remote* into *local*: nested dicts present on both sides
+    are merged recursively; for all other values the remote value wins.
+
+    This is the canonical conflict resolution strategy used across the Starfish
+    protocol — both the client SDK and the server-side replica manager rely on it.
+    """
+    merged = {**local}
+    for key, remote_val in remote.items():
+        local_val = merged.get(key)
+        if isinstance(remote_val, dict) and isinstance(local_val, dict):
+            merged[key] = deep_merge(local_val, remote_val)
+        else:
+            merged[key] = remote_val
+    return merged

starfish_protocol-1.0.0/starfish_protocol/types.py

@@ -0,0 +1,22 @@
+"""Shared wire-format types for the Starfish sync protocol."""
+
+
+from dataclasses import dataclass
+from typing import Any, Union
+
+Timestamps = dict[str, Union[int, "Timestamps"]]
+
+
+@dataclass
+class PullResult:
+    data: dict[str, Any]
+    hash: str
+    timestamp: int
+    author_pubkey: str | None = None
+    author_signature: str | None = None
+
+
+@dataclass
+class PushSuccess:
+    hash: str
+    timestamp: int

starfish_protocol-1.0.0/starfish_protocol.egg-info/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: starfish-protocol
+Version: 1.0.0
+Summary: Shared protocol primitives for the Starfish sync protocol
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=41.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

starfish_protocol-1.0.0/starfish_protocol.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+pyproject.toml
+starfish_protocol/__init__.py
+starfish_protocol/crypto.py
+starfish_protocol/hash.py
+starfish_protocol/merge.py
+starfish_protocol/types.py
+starfish_protocol.egg-info/PKG-INFO
+starfish_protocol.egg-info/SOURCES.txt
+starfish_protocol.egg-info/dependency_links.txt
+starfish_protocol.egg-info/requires.txt
+starfish_protocol.egg-info/top_level.txt
+tests/test_hash.py

starfish_protocol-1.0.0/starfish_protocol.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

starfish_protocol-1.0.0/starfish_protocol.egg-info/requires.txt

@@ -0,0 +1,5 @@
+cryptography>=41.0
+
+[dev]
+pytest>=7.0
+pytest-asyncio>=0.21

starfish_protocol-1.0.0/starfish_protocol.egg-info/top_level.txt

@@ -0,0 +1 @@
+starfish_protocol

starfish_protocol-1.0.0/tests/test_hash.py

@@ -0,0 +1,23 @@
+"""Tests for hashing using shared test vectors."""
+
+import json
+import pathlib
+
+import pytest
+
+from starfish_protocol.hash import stable_stringify, compute_hash
+
+VECTORS_PATH = pathlib.Path(__file__).parent.parent.parent.parent.parent / "tests" / "test-vectors" / "hash.json"
+VECTORS = json.loads(VECTORS_PATH.read_text())
+
+
+@pytest.mark.parametrize("case", VECTORS["stableStringify"])
+def test_stable_stringify(case):
+    result = stable_stringify(case["input"])
+    assert result == case["expected"]
+
+
+@pytest.mark.parametrize("case", VECTORS["computeHash"])
+def test_compute_hash(case):
+    assert stable_stringify(case["input"]) == case["stableJson"]
+    assert compute_hash(case["input"]) == case["expectedHash"]