tibet-ping 0.1.0__tar.gz

tibet_ping-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+*.egg
+.eggs/

tibet_ping-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: tibet-ping
+Version: 0.1.0
+Summary: Intent-based discovery and communication protocol with TIBET provenance. ICMP replacement with identity, trust, and context.
+Project-URL: Homepage, https://humotica.com
+Project-URL: Repository, https://github.com/Humotica/tibet-ping
+Author-email: "J. van de Meent" <jasper@humotica.com>, "R. AI" <root_idd@humotica.nl>
+License: MIT
+Keywords: airlock,beacon,bootstrap,discovery,hub,intent,iot,jis,mesh,ping,pod,provenance,station,tibet,trust,vouching
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Telecommunications Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Requires-Dist: tibet-core>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: overlay
+Requires-Dist: tibet-overlay>=0.1.1; extra == 'overlay'
+Description-Content-Type: text/markdown
+
+# tibet-ping
+
+**Intent-based discovery and communication protocol with TIBET provenance.**
+
+ICMP ping is dumb: "are you there?" → "yes". No identity, no intent, no trust.
+
+tibet-ping replaces this with a TIBET token as handshake. Every ping carries identity (JIS), intent, context, and purpose. Responses are trust-gated through Airlock zones.
+
+## Features
+
+- **PingPacket** — TIBET-backed ping with identity, intent, context, purpose
+- **NonceTracker** — Replay protection (30-second time window)
+- **Airlock** — Trust-gated access (GROEN/GEEL/ROOD zones) with rules engine
+- **Vouching** — Trust delegation for device groups (solves HITL scaling)
+- **Topology** — Hub/Hubby/Pod/Station network modeling
+- **Beacon** — Airgapped bootstrap for new devices (chicken-and-egg solved)
+
+## Quick Start
+
+```python
+from tibet_ping import PingNode, PingDecision
+
+# Create nodes
+hub = PingNode("jis:home:hub")
+sensor = PingNode("jis:home:sensor_temp")
+
+# Hub trusts sensor
+hub.set_trust("jis:home:sensor_temp", 0.9)
+
+# Sensor pings hub
+packet = sensor.ping(
+    target="jis:home:hub",
+    intent="temperature.report",
+    purpose="Periodic temperature reading",
+    payload={"celsius": 21.5},
+)
+
+# Hub receives and processes
+response = hub.receive(packet)
+assert response.decision == PingDecision.ACCEPT
+assert response.airlock_zone == "GROEN"
+```
+
+## Airlock Zones
+
+| Zone | Trust | Action |
+|------|-------|--------|
+| **GROEN** | >= 0.7 | Auto-allow |
+| **GEEL** | 0.3 - 0.7 | Pending (rules or HITL) |
+| **ROOD** | < 0.3 | Silent drop |
+
+## Vouching (HITL Scaling)
+
+```python
+# Hub vouches for 50 sensors at once
+hub.vouch(
+    vouched_dids=["jis:home:s1", "jis:home:s2", ...],
+    my_trust=0.9,
+    vouch_factor=0.7,  # Vouched trust = 0.9 * 0.7 = 0.63
+)
+```
+
+## Beacon Bootstrap
+
+```python
+# New device broadcasts beacon (no secrets!)
+beacon = new_device.broadcast_beacon(
+    capabilities=["temperature"],
+    device_type="sensor",
+)
+
+# Hub auto-vouches or escalates to HITL
+response = hub.handle_beacon(beacon)
+```
+
+## License
+
+MIT — Humotica AI Lab 2025-2026

tibet_ping-0.1.0/README.md

@@ -0,0 +1,78 @@
+# tibet-ping
+
+**Intent-based discovery and communication protocol with TIBET provenance.**
+
+ICMP ping is dumb: "are you there?" → "yes". No identity, no intent, no trust.
+
+tibet-ping replaces this with a TIBET token as handshake. Every ping carries identity (JIS), intent, context, and purpose. Responses are trust-gated through Airlock zones.
+
+## Features
+
+- **PingPacket** — TIBET-backed ping with identity, intent, context, purpose
+- **NonceTracker** — Replay protection (30-second time window)
+- **Airlock** — Trust-gated access (GROEN/GEEL/ROOD zones) with rules engine
+- **Vouching** — Trust delegation for device groups (solves HITL scaling)
+- **Topology** — Hub/Hubby/Pod/Station network modeling
+- **Beacon** — Airgapped bootstrap for new devices (chicken-and-egg solved)
+
+## Quick Start
+
+```python
+from tibet_ping import PingNode, PingDecision
+
+# Create nodes
+hub = PingNode("jis:home:hub")
+sensor = PingNode("jis:home:sensor_temp")
+
+# Hub trusts sensor
+hub.set_trust("jis:home:sensor_temp", 0.9)
+
+# Sensor pings hub
+packet = sensor.ping(
+    target="jis:home:hub",
+    intent="temperature.report",
+    purpose="Periodic temperature reading",
+    payload={"celsius": 21.5},
+)
+
+# Hub receives and processes
+response = hub.receive(packet)
+assert response.decision == PingDecision.ACCEPT
+assert response.airlock_zone == "GROEN"
+```
+
+## Airlock Zones
+
+| Zone | Trust | Action |
+|------|-------|--------|
+| **GROEN** | >= 0.7 | Auto-allow |
+| **GEEL** | 0.3 - 0.7 | Pending (rules or HITL) |
+| **ROOD** | < 0.3 | Silent drop |
+
+## Vouching (HITL Scaling)
+
+```python
+# Hub vouches for 50 sensors at once
+hub.vouch(
+    vouched_dids=["jis:home:s1", "jis:home:s2", ...],
+    my_trust=0.9,
+    vouch_factor=0.7,  # Vouched trust = 0.9 * 0.7 = 0.63
+)
+```
+
+## Beacon Bootstrap
+
+```python
+# New device broadcasts beacon (no secrets!)
+beacon = new_device.broadcast_beacon(
+    capabilities=["temperature"],
+    device_type="sensor",
+)
+
+# Hub auto-vouches or escalates to HITL
+response = hub.handle_beacon(beacon)
+```
+
+## License
+
+MIT — Humotica AI Lab 2025-2026

tibet_ping-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tibet-ping"
+version = "0.1.0"
+description = "Intent-based discovery and communication protocol with TIBET provenance. ICMP replacement with identity, trust, and context."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "J. van de Meent", email = "jasper@humotica.com"},
+    {name = "R. AI", email = "root_idd@humotica.nl"},
+]
+keywords = [
+    "tibet", "jis", "ping", "discovery", "intent", "iot",
+    "mesh", "provenance", "trust", "airlock", "vouching",
+    "beacon", "bootstrap", "hub", "pod", "station"
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Intended Audience :: Telecommunications Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Networking",
+    "Topic :: Security",
+]
+dependencies = [
+    "tibet-core>=0.2.0",
+]
+
+[project.optional-dependencies]
+overlay = ["tibet-overlay>=0.1.1"]
+dev = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://humotica.com"
+Repository = "https://github.com/Humotica/tibet-ping"
+
+[tool.hatch.build.targets.sdist]
+include = ["/src"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tibet_ping"]

tibet_ping-0.1.0/src/tibet_ping/__init__.py

@@ -0,0 +1,82 @@
+"""
+tibet-ping: Intent-Based Discovery & Communication Protocol.
+
+ICMP ping is dumb: "are you there?" → "yes". No identity, no intent, no trust.
+tibet-ping replaces this with a TIBET token as handshake.
+
+Every ping carries:
+    Identity  — JIS DID (who are you)
+    Intent    — what do you want
+    Context   — pod, station, network
+    Purpose   — why are you pinging
+
+Responses are trust-gated through Airlock (GROEN/GEEL/ROOD).
+
+Usage::
+
+    from tibet_ping import PingNode
+
+    # Create a node
+    hub = PingNode("jis:home:hub")
+    sensor = PingNode("jis:home:sensor_temp")
+
+    # Hub trusts sensor
+    hub.set_trust("jis:home:sensor_temp", 0.9)
+
+    # Sensor pings hub
+    packet = sensor.ping(
+        target="jis:home:hub",
+        intent="temperature.report",
+        purpose="Periodic temperature reading",
+        payload={"celsius": 21.5},
+    )
+
+    # Hub receives and processes
+    response = hub.receive(packet)
+    print(response.decision)    # PingDecision.ACCEPT
+    print(response.airlock_zone)  # "GROEN"
+"""
+
+from .proto import PingPacket, PingResponse, PingType, Priority, RoutingMode, PingDecision
+from .nonce import NonceTracker
+from .airlock import Airlock, AirlockRule, AirlockZone, PendingPing
+from .vouch import Vouch, VouchRegistry
+from .topology import TopologyManager, Pod, Station, NodeRole
+from .beacon import Beacon, BeaconHandler, BeaconResponse
+from .handler import PingHandler
+from .node import PingNode
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Node (main entry point)
+    "PingNode",
+    # Proto
+    "PingPacket",
+    "PingResponse",
+    "PingType",
+    "Priority",
+    "RoutingMode",
+    "PingDecision",
+    # Nonce
+    "NonceTracker",
+    # Airlock
+    "Airlock",
+    "AirlockRule",
+    "AirlockZone",
+    "PendingPing",
+    # Vouch
+    "Vouch",
+    "VouchRegistry",
+    # Topology
+    "TopologyManager",
+    "Pod",
+    "Station",
+    "NodeRole",
+    # Beacon
+    "Beacon",
+    "BeaconHandler",
+    "BeaconResponse",
+    # Handler
+    "PingHandler",
+]

tibet_ping-0.1.0/src/tibet_ping/airlock.py

@@ -0,0 +1,176 @@
+"""
+Trust-gated access control for incoming pings.
+
+Three zones:
+    GROEN — Known + trusted → auto-allow
+    GEEL  — Unknown → pending (rules or HITL)
+    ROOD  — Untrusted → silent drop (no info leak)
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Callable, Dict, List, Optional, Tuple
+
+from .proto import PingDecision, PingPacket
+
+
+class AirlockZone(Enum):
+    """Three-zone trust model."""
+    GROEN = "GROEN"
+    GEEL = "GEEL"
+    ROOD = "ROOD"
+
+
+@dataclass
+class AirlockRule:
+    """
+    Pattern-based auto-decision rule.
+
+    Patterns support simple glob: "*" matches everything,
+    "prefix*" matches start, "*suffix" matches end.
+
+    Examples:
+        {"source_did": "jis:home:*", "intent": "temperature.*"} → GROEN
+        {"intent": "door.unlock"} → GEEL (force HITL)
+    """
+    rule_id: str
+    name: str
+    pattern: Dict[str, str]
+    decision: PingDecision
+    zone: AirlockZone
+    priority: int = 50  # Higher = checked first
+
+    def matches(self, packet: PingPacket, sender_trust: float) -> bool:
+        """Check if packet matches this rule's pattern."""
+        for key, pattern in self.pattern.items():
+            if key == "source_did":
+                if not _glob_match(packet.source_did, pattern):
+                    return False
+            elif key == "intent":
+                if not _glob_match(packet.intent, pattern):
+                    return False
+            elif key == "pod_id":
+                if packet.pod_id != pattern:
+                    return False
+            elif key == "ping_type":
+                if packet.ping_type.value != pattern:
+                    return False
+            elif key == "min_trust":
+                if sender_trust < float(pattern):
+                    return False
+        return True
+
+
+def _glob_match(value: str, pattern: str) -> bool:
+    """Simple glob: *, prefix*, *suffix, exact."""
+    if pattern == "*":
+        return True
+    if pattern.startswith("*") and pattern.endswith("*") and len(pattern) > 2:
+        return pattern[1:-1] in value
+    if pattern.endswith("*"):
+        return value.startswith(pattern[:-1])
+    if pattern.startswith("*"):
+        return value.endswith(pattern[1:])
+    return value == pattern
+
+
+@dataclass
+class PendingPing:
+    """Ping awaiting HITL decision."""
+    packet: PingPacket
+    sender_trust: float
+    reason: str
+
+
+class Airlock:
+    """
+    Trust-gated access control.
+
+    Rules are checked first (highest priority wins).
+    Then trust thresholds determine zone.
+    GEEL pings go to pending queue and trigger on_hitl_needed callback.
+    """
+
+    def __init__(
+        self,
+        trust_threshold_groen: float = 0.7,
+        trust_threshold_rood: float = 0.3,
+        on_hitl_needed: Optional[Callable[[PendingPing], None]] = None,
+    ) -> None:
+        self.trust_threshold_groen = trust_threshold_groen
+        self.trust_threshold_rood = trust_threshold_rood
+        self.on_hitl_needed = on_hitl_needed
+        self._rules: List[AirlockRule] = []
+        self.pending: Dict[str, PendingPing] = {}
+
+    def add_rule(self, rule: AirlockRule) -> None:
+        """Add a rule (auto-sorted by priority, highest first)."""
+        self._rules.append(rule)
+        self._rules.sort(key=lambda r: r.priority, reverse=True)
+
+    @property
+    def rules(self) -> List[AirlockRule]:
+        return list(self._rules)
+
+    def gate(
+        self, packet: PingPacket, sender_trust: float
+    ) -> Tuple[AirlockZone, Optional[AirlockRule]]:
+        """
+        Determine zone for a packet.
+        Returns (zone, matched_rule_or_None).
+        """
+        # Rules first
+        for rule in self._rules:
+            if rule.matches(packet, sender_trust):
+                return (rule.zone, rule)
+
+        # Trust thresholds
+        if sender_trust >= self.trust_threshold_groen:
+            return (AirlockZone.GROEN, None)
+        if sender_trust < self.trust_threshold_rood:
+            return (AirlockZone.ROOD, None)
+
+        return (AirlockZone.GEEL, None)
+
+    def process(self, packet: PingPacket, sender_trust: float) -> PingDecision:
+        """
+        Full processing: gate → decision → pending queue if GEEL.
+        """
+        zone, rule = self.gate(packet, sender_trust)
+
+        if zone == AirlockZone.GROEN:
+            return PingDecision.ACCEPT
+        if zone == AirlockZone.ROOD:
+            return PingDecision.REJECT
+
+        # GEEL: add to pending
+        pending = PendingPing(
+            packet=packet,
+            sender_trust=sender_trust,
+            reason=f"Trust {sender_trust:.2f} in GEEL zone"
+            + (f" (rule: {rule.name})" if rule else ""),
+        )
+        self.pending[packet.packet_id] = pending
+
+        if self.on_hitl_needed:
+            self.on_hitl_needed(pending)
+
+        return PingDecision.PENDING
+
+    def approve_pending(self, packet_id: str) -> bool:
+        """HITL approves a pending ping."""
+        return self.pending.pop(packet_id, None) is not None
+
+    def reject_pending(self, packet_id: str) -> bool:
+        """HITL rejects a pending ping."""
+        return self.pending.pop(packet_id, None) is not None
+
+    def stats(self) -> dict:
+        return {
+            "rules": len(self._rules),
+            "pending_count": len(self.pending),
+            "thresholds": {
+                "groen": self.trust_threshold_groen,
+                "rood": self.trust_threshold_rood,
+            },
+        }

tibet_ping-0.1.0/src/tibet_ping/beacon.py

@@ -0,0 +1,179 @@
+"""
+Bootstrap beacon for new devices (airgapped, local-only).
+
+Solves the chicken-and-egg problem: new device knows nobody.
+Beacon broadcasts on local network. Hub can auto-vouch or escalate to HITL.
+
+NO secrets in beacons — assume adversarial broadcast medium.
+"""
+
+import re
+import secrets
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Callable, Dict, List, Optional
+
+
+@dataclass
+class Beacon:
+    """
+    Bootstrap beacon broadcast by a new device.
+
+    Contains only public information:
+    - JIS DID
+    - Capabilities
+    - Requested pod
+    - Public key HASH (not the key itself!)
+    """
+    beacon_id: str
+    source_did: str
+    capabilities: List[str] = field(default_factory=list)
+    requested_pod: Optional[str] = None
+    device_type: str = "generic"  # sensor, actuator, gateway, controller
+    public_key_hash: str = ""
+    timestamp: str = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+
+    def is_fresh(self, max_age_seconds: int = 300) -> bool:
+        """Check if beacon is recent enough (default 5 minutes)."""
+        now = datetime.now(timezone.utc)
+        try:
+            ts = self.timestamp.replace("Z", "+00:00")
+            beacon_time = datetime.fromisoformat(ts)
+            if beacon_time.tzinfo is None:
+                beacon_time = beacon_time.replace(tzinfo=timezone.utc)
+            age = (now - beacon_time).total_seconds()
+            return age <= max_age_seconds
+        except (ValueError, OSError):
+            return False
+
+    def to_dict(self) -> dict:
+        return {
+            "beacon_id": self.beacon_id,
+            "source_did": self.source_did,
+            "capabilities": self.capabilities,
+            "requested_pod": self.requested_pod,
+            "device_type": self.device_type,
+            "public_key_hash": self.public_key_hash,
+            "timestamp": self.timestamp,
+        }
+
+    @classmethod
+    def create(
+        cls,
+        source_did: str,
+        capabilities: Optional[List[str]] = None,
+        requested_pod: Optional[str] = None,
+        device_type: str = "generic",
+        public_key_hash: str = "",
+    ) -> "Beacon":
+        """Factory method with auto-generated beacon_id."""
+        return cls(
+            beacon_id=f"beacon_{secrets.token_hex(8)}",
+            source_did=source_did,
+            capabilities=capabilities or [],
+            requested_pod=requested_pod,
+            device_type=device_type,
+            public_key_hash=public_key_hash,
+        )
+
+
+@dataclass
+class BeaconResponse:
+    """Hub response to a beacon."""
+    response_id: str
+    in_response_to: str  # beacon_id
+    hub_did: str
+    decision: str  # "auto_vouched", "hitl_pending", "rejected"
+    vouch_id: Optional[str] = None
+    assigned_pod: Optional[str] = None
+    message: str = ""
+    timestamp: str = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+
+
+class BeaconHandler:
+    """
+    Handle beacon broadcasts for bootstrapping.
+
+    auto_vouch_rules: list of dicts with matching conditions.
+    Each rule can match on: device_type, required_capabilities, source_pattern.
+    If matched, the beacon is auto-vouched into the specified pod.
+    """
+
+    def __init__(
+        self,
+        auto_vouch_rules: Optional[List[dict]] = None,
+        on_hitl_needed: Optional[Callable[["Beacon"], None]] = None,
+    ) -> None:
+        self.auto_vouch_rules = auto_vouch_rules or []
+        self.on_hitl_needed = on_hitl_needed
+        self._recent: Dict[str, Beacon] = {}
+
+    def handle_beacon(self, beacon: Beacon, hub_did: str) -> BeaconResponse:
+        """
+        Process an incoming beacon.
+
+        1. Check freshness
+        2. Try auto-vouch rules
+        3. Escalate to HITL if no rule matches
+        """
+        resp_id = f"resp_{beacon.beacon_id}"
+
+        if not beacon.is_fresh():
+            return BeaconResponse(
+                response_id=resp_id,
+                in_response_to=beacon.beacon_id,
+                hub_did=hub_did,
+                decision="rejected",
+                message="Beacon too old",
+            )
+
+        # Track recent beacons
+        self._recent[beacon.beacon_id] = beacon
+
+        # Try auto-vouch rules
+        for rule in self.auto_vouch_rules:
+            if self._matches_rule(beacon, rule):
+                vouch_id = f"vouch_{secrets.token_hex(8)}"
+                return BeaconResponse(
+                    response_id=resp_id,
+                    in_response_to=beacon.beacon_id,
+                    hub_did=hub_did,
+                    decision="auto_vouched",
+                    vouch_id=vouch_id,
+                    assigned_pod=rule.get("pod_id"),
+                    message=f"Auto-vouched via rule: {rule.get('name', 'unnamed')}",
+                )
+
+        # No rule matched → HITL
+        if self.on_hitl_needed:
+            self.on_hitl_needed(beacon)
+
+        return BeaconResponse(
+            response_id=resp_id,
+            in_response_to=beacon.beacon_id,
+            hub_did=hub_did,
+            decision="hitl_pending",
+            message="Awaiting HITL approval",
+        )
+
+    @staticmethod
+    def _matches_rule(beacon: Beacon, rule: dict) -> bool:
+        """Check if beacon matches an auto-vouch rule."""
+        if "device_type" in rule:
+            if beacon.device_type != rule["device_type"]:
+                return False
+
+        if "required_capabilities" in rule:
+            required = set(rule["required_capabilities"])
+            if not required.issubset(set(beacon.capabilities)):
+                return False
+
+        if "source_pattern" in rule:
+            if not re.match(rule["source_pattern"], beacon.source_did):
+                return False
+
+        return True