cairn-p2p 0.2.0__tar.gz

cairn_p2p-0.2.0/.gitignore

@@ -0,0 +1,49 @@
+target/
+
+# Dependencies
+node_modules/
+vendor/
+.venv/
+composer.lock
+
+# Build artifacts
+dist/
+
+# Caches
+__pycache__/
+.phpunit.cache/
+*.pyc
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Coverage reports
+coverage/
+htmlcov/
+*.lcov
+.nyc_output/
+
+# PHP
+.phpunit.result.cache
+composer.phar
+
+# Python
+*.egg-info/
+*.egg
+.eggs/
+
+# Go
+*.test
+cairn-conformance-runner-go
+
+# Environment / secrets
+.env
+.env.*

cairn_p2p-0.2.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: cairn-p2p
+Version: 0.2.0
+Summary: P2P connectivity library
+Project-URL: Repository, https://github.com/moukrea/cairn
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: base58>=2.1
+Requires-Dist: cbor2>=5.6
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: qrcode>=7.4
+Requires-Dist: spake2>=0.9
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Provides-Extra: discovery
+Requires-Dist: kademlia>=2.2; extra == 'discovery'
+Requires-Dist: zeroconf>=0.131; extra == 'discovery'
+Provides-Extra: libp2p
+Requires-Dist: libp2p; extra == 'libp2p'

cairn_p2p-0.2.0/README.md

@@ -0,0 +1,52 @@
+# cairn-py
+
+Python implementation of the cairn P2P connectivity library.
+
+## Installation
+
+```bash
+pip install cairn
+```
+
+## Requirements
+
+- Python 3.11+
+
+## Quick Start
+
+```python
+import asyncio
+from cairn import CairnNode
+
+async def main():
+    node = await CairnNode.create()
+    peer = await node.pair_with_pin("123456")
+    await peer.send(b"hello")
+
+asyncio.run(main())
+```
+
+## API Overview
+
+- `CairnNode` -- Main entry point, manages identity, sessions, and discovery
+- `Session` -- Persistent encrypted session with a peer
+- `PeerIdentity` -- Ed25519 identity with Peer ID derivation
+- `CairnConfig` -- Configuration with tier presets
+
+## Key Dependencies
+
+- `cryptography` -- AEAD encryption, key derivation
+- `spake2` -- Password-authenticated key exchange for pairing
+- `cbor2` -- CBOR wire protocol encoding
+- `websockets` -- WebSocket transport
+- `httpx` -- HTTP client for signaling
+
+## Optional Dependencies
+
+- `libp2p` -- libp2p transport integration
+- `zeroconf` -- mDNS LAN discovery
+- `kademlia` -- DHT discovery
+
+## License
+
+Licensed under the [MIT License](../../LICENSE).

cairn_p2p-0.2.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cairn-p2p"
+version = "0.2.0"
+description = "P2P connectivity library"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = [
+    "base58>=2.1",
+    "cbor2>=5.6",
+    "cryptography>=42.0",
+    "spake2>=0.9",
+    "qrcode>=7.4",
+    "websockets>=12.0",
+    "httpx>=0.27",
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Repository = "https://github.com/moukrea/cairn"
+
+[project.optional-dependencies]
+libp2p = ["libp2p"]
+discovery = ["zeroconf>=0.131", "kademlia>=2.2"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "ruff>=0.3"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cairn"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]

cairn_p2p-0.2.0/src/cairn/__init__.py

@@ -0,0 +1,55 @@
+"""cairn - P2P connectivity library."""
+
+from cairn.config import (
+    CairnConfig,
+    MeshSettings,
+    ReconnectionPolicy,
+    TurnServer,
+)
+from cairn.errors import (
+    AuthenticationFailedError,
+    CairnError,
+    ErrorBehavior,
+    MeshRouteNotFoundError,
+    PairingExpiredError,
+    PairingRejectedError,
+    PeerUnreachableError,
+    SessionExpiredError,
+    TransportExhaustedError,
+    VersionMismatchError,
+)
+from cairn.node import (
+    Channel,
+    NetworkInfo,
+    Node,
+    NodeEvent,
+    NodeEventType,
+    Session,
+    create,
+    create_server,
+)
+
+__all__ = [
+    "AuthenticationFailedError",
+    "CairnConfig",
+    "CairnError",
+    "Channel",
+    "ErrorBehavior",
+    "MeshRouteNotFoundError",
+    "MeshSettings",
+    "NetworkInfo",
+    "Node",
+    "NodeEvent",
+    "NodeEventType",
+    "PairingExpiredError",
+    "PairingRejectedError",
+    "PeerUnreachableError",
+    "ReconnectionPolicy",
+    "Session",
+    "SessionExpiredError",
+    "TransportExhaustedError",
+    "TurnServer",
+    "VersionMismatchError",
+    "create",
+    "create_server",
+]

cairn_p2p-0.2.0/src/cairn/channel.py

@@ -0,0 +1,179 @@
+"""Channel multiplexing over sessions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+
+import cbor2
+
+RESERVED_CHANNEL_PREFIX: str = "__cairn_"
+CHANNEL_FORWARD: str = "__cairn_forward"
+CHANNEL_INIT_TYPE: int = 0x0303
+
+
+def validate_channel_name(name: str) -> None:
+    """Validate that a channel name is not reserved.
+
+    Raises ValueError if the name is empty or uses the reserved prefix.
+    """
+    if not name:
+        raise ValueError("channel name must not be empty")
+    if name.startswith(RESERVED_CHANNEL_PREFIX):
+        raise ValueError(
+            f"channel name '{name}' uses reserved prefix "
+            f"'{RESERVED_CHANNEL_PREFIX}'"
+        )
+
+
+class ChannelState(Enum):
+    """Channel lifecycle states."""
+
+    OPENING = auto()
+    OPEN = auto()
+    REJECTED = auto()
+    CLOSED = auto()
+
+
+class Channel:
+    """A named channel multiplexed over a session stream."""
+
+    def __init__(
+        self,
+        name: str,
+        stream_id: int,
+        metadata: bytes | None = None,
+    ) -> None:
+        self.name = name
+        self.stream_id = stream_id
+        self.state = ChannelState.OPENING
+        self.metadata = metadata
+
+    @property
+    def is_open(self) -> bool:
+        return self.state == ChannelState.OPEN
+
+    def accept(self) -> None:
+        """Transition to Open state."""
+        if self.state != ChannelState.OPENING:
+            raise ValueError(
+                f"cannot accept channel '{self.name}' "
+                f"in state {self.state.name}"
+            )
+        self.state = ChannelState.OPEN
+
+    def reject(self) -> None:
+        """Transition to Rejected state."""
+        if self.state != ChannelState.OPENING:
+            raise ValueError(
+                f"cannot reject channel '{self.name}' "
+                f"in state {self.state.name}"
+            )
+        self.state = ChannelState.REJECTED
+
+    def close(self) -> None:
+        """Transition to Closed state."""
+        if self.state == ChannelState.CLOSED:
+            raise ValueError(
+                f"channel '{self.name}' is already closed"
+            )
+        self.state = ChannelState.CLOSED
+
+
+@dataclass
+class ChannelInit:
+    """First message sent on a newly opened stream."""
+
+    channel_name: str
+    metadata: bytes | None = None
+
+    def to_cbor(self) -> bytes:
+        """Encode to CBOR."""
+        m: dict[str, object] = {
+            "channel_name": self.channel_name
+        }
+        if self.metadata is not None:
+            m["metadata"] = self.metadata
+        return cbor2.dumps(m)
+
+    @classmethod
+    def from_cbor(cls, data: bytes) -> ChannelInit:
+        """Decode from CBOR."""
+        m = cbor2.loads(data)
+        return cls(
+            channel_name=m["channel_name"],
+            metadata=m.get("metadata"),
+        )
+
+
+class ChannelManager:
+    """Manages channels within a session."""
+
+    def __init__(self) -> None:
+        self._channels: dict[int, Channel] = {}
+
+    def open_channel(
+        self,
+        name: str,
+        stream_id: int,
+        metadata: bytes | None = None,
+    ) -> ChannelInit:
+        """Open a new channel on a given stream.
+
+        Returns the ChannelInit payload to send.
+        """
+        validate_channel_name(name)
+        if stream_id in self._channels:
+            raise ValueError(
+                f"stream {stream_id} already has a channel"
+            )
+
+        channel = Channel(name, stream_id, metadata)
+        self._channels[stream_id] = channel
+        return ChannelInit(
+            channel_name=name, metadata=metadata
+        )
+
+    def handle_channel_init(
+        self, stream_id: int, init: ChannelInit
+    ) -> None:
+        """Handle an incoming ChannelInit from a remote peer."""
+        if stream_id in self._channels:
+            raise ValueError(
+                f"stream {stream_id} already has a channel"
+            )
+        channel = Channel(
+            init.channel_name, stream_id, init.metadata
+        )
+        self._channels[stream_id] = channel
+
+    def accept_channel(self, stream_id: int) -> None:
+        """Accept an incoming channel."""
+        channel = self._get_channel(stream_id)
+        channel.accept()
+
+    def reject_channel(self, stream_id: int) -> None:
+        """Reject an incoming channel."""
+        channel = self._get_channel(stream_id)
+        channel.reject()
+
+    def close_channel(self, stream_id: int) -> None:
+        """Close a channel."""
+        channel = self._get_channel(stream_id)
+        channel.close()
+
+    def get_channel(self, stream_id: int) -> Channel | None:
+        """Get a channel by stream ID."""
+        return self._channels.get(stream_id)
+
+    @property
+    def channel_count(self) -> int:
+        return len(self._channels)
+
+    def _get_channel(self, stream_id: int) -> Channel:
+        channel = self._channels.get(stream_id)
+        if channel is None:
+            raise ValueError(
+                f"no channel on stream {stream_id}"
+            )
+        return channel

cairn_p2p-0.2.0/src/cairn/config.py

@@ -0,0 +1,175 @@
+"""Configuration builder with tier presets (spec 11, section 1)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# ---------------------------------------------------------------------------
+# Default STUN servers
+# ---------------------------------------------------------------------------
+
+DEFAULT_STUN_SERVERS: list[str] = [
+    "stun:stun.l.google.com:19302",
+    "stun:stun1.l.google.com:19302",
+    "stun:stun.cloudflare.com:3478",
+]
+
+
+# ---------------------------------------------------------------------------
+# Supporting dataclasses
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class TurnServer:
+    """TURN relay server credentials."""
+
+    url: str = ""
+    username: str = ""
+    credential: str = ""
+
+
+@dataclass
+class ReconnectionPolicy:
+    """Reconnection and timeout policy (spec section 2.2)."""
+
+    connect_timeout: float = 30.0
+    transport_timeout: float = 10.0
+    reconnect_max_duration: float = 3600.0
+    reconnect_backoff_initial: float = 1.0
+    reconnect_backoff_max: float = 60.0
+    reconnect_backoff_factor: float = 2.0
+    rendezvous_poll_interval: float = 30.0
+    session_expiry: float = 86400.0
+    pairing_payload_expiry: float = 300.0
+
+
+@dataclass
+class MeshSettings:
+    """Mesh routing settings (spec section 1.2)."""
+
+    mesh_enabled: bool = False
+    max_hops: int = 3
+    relay_willing: bool = False
+    relay_capacity: int = 10
+
+
+# ---------------------------------------------------------------------------
+# CairnConfig
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class CairnConfig:
+    """Top-level configuration (spec section 1.1).
+
+    Every field has a sensible default, enabling zero-config usage (Tier 0).
+    """
+
+    stun_servers: list[str] = field(
+        default_factory=lambda: list(DEFAULT_STUN_SERVERS)
+    )
+    turn_servers: list[TurnServer] = field(
+        default_factory=list
+    )
+    signaling_servers: list[str] = field(
+        default_factory=list
+    )
+    tracker_urls: list[str] = field(default_factory=list)
+    bootstrap_nodes: list[str] = field(default_factory=list)
+    reconnection_policy: ReconnectionPolicy = field(
+        default_factory=ReconnectionPolicy
+    )
+    mesh_settings: MeshSettings = field(
+        default_factory=MeshSettings
+    )
+    server_mode: bool = False
+
+    # --- Tier presets ---
+
+    @classmethod
+    def tier0(cls) -> CairnConfig:
+        """Tier 0: fully decentralized, zero-config."""
+        return cls()
+
+    @classmethod
+    def tier1(
+        cls,
+        signaling_servers: list[str] | None = None,
+        turn_servers: list[TurnServer] | None = None,
+    ) -> CairnConfig:
+        """Tier 1: add signaling server and optional TURN relay."""
+        return cls(
+            signaling_servers=signaling_servers or [],
+            turn_servers=turn_servers or [],
+        )
+
+    @classmethod
+    def tier2(
+        cls,
+        signaling_servers: list[str] | None = None,
+        turn_servers: list[TurnServer] | None = None,
+        tracker_urls: list[str] | None = None,
+        bootstrap_nodes: list[str] | None = None,
+    ) -> CairnConfig:
+        """Tier 2: self-hosted infrastructure."""
+        return cls(
+            signaling_servers=signaling_servers or [],
+            turn_servers=turn_servers or [],
+            tracker_urls=tracker_urls or [],
+            bootstrap_nodes=bootstrap_nodes or [],
+        )
+
+    @classmethod
+    def tier3(
+        cls,
+        signaling_servers: list[str] | None = None,
+        turn_servers: list[TurnServer] | None = None,
+        tracker_urls: list[str] | None = None,
+        bootstrap_nodes: list[str] | None = None,
+        mesh_settings: MeshSettings | None = None,
+    ) -> CairnConfig:
+        """Tier 3: fully self-hosted with mesh routing."""
+        return cls(
+            signaling_servers=signaling_servers or [],
+            turn_servers=turn_servers or [],
+            tracker_urls=tracker_urls or [],
+            bootstrap_nodes=bootstrap_nodes or [],
+            mesh_settings=mesh_settings or MeshSettings(
+                mesh_enabled=True
+            ),
+        )
+
+    @classmethod
+    def default_server(cls) -> CairnConfig:
+        """Default server-mode config."""
+        return cls(
+            server_mode=True,
+            reconnection_policy=ReconnectionPolicy(
+                session_expiry=7 * 86400.0,
+            ),
+            mesh_settings=MeshSettings(
+                relay_willing=True,
+            ),
+        )
+
+    def validate(self) -> None:
+        """Validate configuration. Raises ValueError on invalid settings."""
+        if not self.stun_servers and not self.turn_servers:
+            raise ValueError(
+                "stun_servers must not be empty unless "
+                "turn_servers are configured"
+            )
+
+        if self.reconnection_policy.reconnect_backoff_factor <= 1.0:
+            raise ValueError(
+                "reconnect_backoff_factor must be greater than 1.0"
+            )
+
+        if (
+            self.mesh_settings.max_hops < 1
+            or self.mesh_settings.max_hops > 10
+        ):
+            raise ValueError(
+                "max_hops must be between 1 and 10"
+            )

cairn_p2p-0.2.0/src/cairn/crypto/__init__.py

@@ -0,0 +1,79 @@
+"""Cryptographic primitives: identity, key exchange, AEAD, HKDF, Noise, SPAKE2."""
+
+from cairn.crypto.aead import (
+    AES_GCM_TAG_SIZE,
+    CHACHA_TAG_SIZE,
+    KEY_SIZE,
+    NONCE_SIZE,
+    CipherSuite,
+    aead_decrypt,
+    aead_encrypt,
+)
+from cairn.crypto.identity import (
+    IdentityKeypair,
+    PeerId,
+    X25519Keypair,
+    peer_id_from_public_key,
+    verify_signature,
+)
+from cairn.crypto.kdf import (
+    HKDF_INFO_CHAIN_KEY,
+    HKDF_INFO_MESSAGE_KEY,
+    HKDF_INFO_RENDEZVOUS,
+    HKDF_INFO_SAS,
+    HKDF_INFO_SESSION_KEY,
+    hkdf_sha256,
+)
+from cairn.crypto.noise import (
+    EMOJI_TABLE,
+    HandshakeResult,
+    NoiseXXHandshake,
+    Role,
+    derive_emoji_sas,
+    derive_numeric_sas,
+)
+from cairn.crypto.ratchet import (
+    DoubleRatchet,
+    RatchetConfig,
+    RatchetHeader,
+)
+from cairn.crypto.spake2_pake import Spake2Session
+from cairn.crypto.storage import (
+    FilesystemKeyStorage,
+    InMemoryKeyStorage,
+    KeyStorage,
+)
+
+__all__ = [
+    "AES_GCM_TAG_SIZE",
+    "CHACHA_TAG_SIZE",
+    "CipherSuite",
+    "DoubleRatchet",
+    "EMOJI_TABLE",
+    "HKDF_INFO_CHAIN_KEY",
+    "HKDF_INFO_MESSAGE_KEY",
+    "HKDF_INFO_RENDEZVOUS",
+    "HKDF_INFO_SAS",
+    "HKDF_INFO_SESSION_KEY",
+    "HandshakeResult",
+    "IdentityKeypair",
+    "KEY_SIZE",
+    "NONCE_SIZE",
+    "NoiseXXHandshake",
+    "PeerId",
+    "RatchetConfig",
+    "RatchetHeader",
+    "Role",
+    "Spake2Session",
+    "X25519Keypair",
+    "FilesystemKeyStorage",
+    "InMemoryKeyStorage",
+    "KeyStorage",
+    "aead_decrypt",
+    "aead_encrypt",
+    "derive_emoji_sas",
+    "derive_numeric_sas",
+    "hkdf_sha256",
+    "peer_id_from_public_key",
+    "verify_signature",
+]