@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/peer_directory.py

@@ -0,0 +1,324 @@
+"""
+Peer Directory — transport address map for the sovereignty mesh.
+
+Maps agent names to their SKComm transport addresses (Syncthing outbox
+paths, WebRTC fingerprints, Tailscale IPs, etc.).
+
+Separate from PeerRecord (PGP identity in peers.py) — this module owns
+the *routing* layer, not the trust/cryptography layer.
+
+Storage: {skcapstone_home}/peers/directory.yaml
+
+Entry format:
+    lumina:
+      address: /home/user/.skcapstone/sync/comms/outbox/lumina
+      transport: syncthing
+      fingerprint: ABCD1234...
+      last_seen: 2026-03-02T...
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+import yaml
+from pydantic import BaseModel, Field
+
+from . import SHARED_ROOT
+
+logger = logging.getLogger("skcapstone.peer_directory")
+
+
+# ---------------------------------------------------------------------------
+# Model
+# ---------------------------------------------------------------------------
+
+
+class DirectoryEntry(BaseModel):
+    """A single peer's transport routing entry.
+
+    Attributes:
+        name: Normalized peer name (lowercase).
+        address: Transport address — Syncthing outbox path, Tailscale IP,
+            WebRTC fingerprint URI, or other transport-specific locator.
+        transport: Transport type label (syncthing, webrtc, tailscale, file).
+        fingerprint: Optional PGP fingerprint for cross-referencing.
+        last_seen: ISO-8601 UTC timestamp of last known activity.
+    """
+
+    name: str
+    address: str
+    transport: str = "syncthing"
+    fingerprint: str = ""
+    last_seen: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# PeerDirectory
+# ---------------------------------------------------------------------------
+
+
+class PeerDirectory:
+    """Transport address directory for the sovereign agent mesh.
+
+    Maps agent names → transport addresses. Separate from the PGP identity
+    peer store (peers.py); this module owns routing, not trust.
+
+    Storage: {home}/peers/directory.yaml
+
+    Args:
+        home: skcapstone home directory. Defaults to SHARED_ROOT (~/.skcapstone).
+    """
+
+    def __init__(self, home: Optional[Path] = None) -> None:
+        self._home = home or Path(SHARED_ROOT).expanduser()
+        self._path = self._home / "peers" / "directory.yaml"
+        self._entries: dict[str, DirectoryEntry] = {}
+        self._loaded = False
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def load(self) -> dict[str, DirectoryEntry]:
+        """Read the directory from disk.
+
+        Safe to call multiple times — idempotent re-load.
+
+        Returns:
+            Dict mapping normalized name -> DirectoryEntry.
+        """
+        if not self._path.exists():
+            self._entries = {}
+            self._loaded = True
+            return {}
+
+        try:
+            raw = yaml.safe_load(self._path.read_text(encoding="utf-8")) or {}
+            entries: dict[str, DirectoryEntry] = {}
+            for name, entry in raw.items():
+                if not isinstance(entry, dict):
+                    continue
+                try:
+                    entries[str(name).lower()] = DirectoryEntry.model_validate(
+                        {"name": str(name).lower(), **entry}
+                    )
+                except Exception as exc:
+                    logger.debug("Skipping malformed entry '%s': %s", name, exc)
+            self._entries = entries
+        except Exception as exc:
+            logger.warning("Failed to load peer directory: %s", exc)
+            self._entries = {}
+
+        self._loaded = True
+        return dict(self._entries)
+
+    def resolve(self, name: str) -> Optional[str]:
+        """Get the transport address for a named peer.
+
+        Args:
+            name: Peer name (case-insensitive).
+
+        Returns:
+            Transport address string, or None if the peer is not in the
+            directory.
+        """
+        self._ensure_loaded()
+        entry = self._entries.get(name.lower())
+        return entry.address if entry else None
+
+    def add_peer(
+        self,
+        name: str,
+        address: str,
+        transport: str = "syncthing",
+        fingerprint: str = "",
+    ) -> DirectoryEntry:
+        """Add or update a peer's transport entry.
+
+        If the peer already exists it is overwritten. Persists atomically.
+
+        Args:
+            name: Peer display name (normalised to lowercase as the key).
+            address: Transport address (path, IP, URI, etc.).
+            transport: Transport type — syncthing, webrtc, tailscale, file.
+            fingerprint: Optional PGP fingerprint for cross-referencing.
+
+        Returns:
+            The created or updated DirectoryEntry.
+        """
+        self._ensure_loaded()
+        entry = DirectoryEntry(
+            name=name.lower(),
+            address=address,
+            transport=transport,
+            fingerprint=fingerprint,
+            last_seen=datetime.now(timezone.utc).isoformat(),
+        )
+        self._entries[name.lower()] = entry
+        self._save()
+        logger.info("Directory: added '%s' → %s (%s)", name, address, transport)
+        return entry
+
+    def remove_peer(self, name: str) -> bool:
+        """Remove a peer from the directory.
+
+        Args:
+            name: Peer name to remove (case-insensitive).
+
+        Returns:
+            True if the peer was found and removed, False otherwise.
+        """
+        self._ensure_loaded()
+        key = name.lower()
+        if key not in self._entries:
+            return False
+        del self._entries[key]
+        self._save()
+        logger.info("Directory: removed '%s'", name)
+        return True
+
+    def list_peers(self) -> list[DirectoryEntry]:
+        """Return all known peers, sorted by name.
+
+        Returns:
+            List of DirectoryEntry sorted alphabetically.
+        """
+        self._ensure_loaded()
+        return sorted(self._entries.values(), key=lambda e: e.name)
+
+    def update_last_seen(self, name: str) -> None:
+        """Touch the last_seen timestamp for a peer (in-place + save).
+
+        Called by the consciousness loop whenever a message arrives from
+        a known peer, so the directory stays current without a full re-add.
+
+        Args:
+            name: Peer name (case-insensitive). No-op if peer is unknown.
+        """
+        self._ensure_loaded()
+        key = name.lower()
+        if key not in self._entries:
+            return
+        self._entries[key].last_seen = datetime.now(timezone.utc).isoformat()
+        self._save()
+
+    def auto_discover(
+        self,
+        heartbeats_dir: Optional[Path] = None,
+    ) -> list[DirectoryEntry]:
+        """Discover peers from heartbeat files and Syncthing outbox dirs.
+
+        Scans two sources and adds any *new* peers (existing entries are
+        never overwritten):
+
+        1. ``{home}/heartbeats/*.json`` — live heartbeat files published by
+           each agent via HeartbeatBeacon.
+        2. ``{home}/sync/comms/outbox/`` — one sub-directory per peer that
+           Syncthing keeps in sync.
+
+        Syncthing outbox path is used as the default address because that
+        is where SKComm writes messages for the peer.
+
+        Args:
+            heartbeats_dir: Override for the heartbeats directory.  Defaults
+                to ``{home}/heartbeats``.
+
+        Returns:
+            List of newly-added DirectoryEntry objects (empty if all peers
+            were already known).
+        """
+        self._ensure_loaded()
+        added: list[DirectoryEntry] = []
+
+        hb_dir = heartbeats_dir or (self._home / "heartbeats")
+
+        # 1. Scan heartbeat files
+        if hb_dir.exists():
+            for hb_file in sorted(hb_dir.glob("*.json")):
+                if hb_file.name.endswith(".tmp"):
+                    continue
+                agent_name = hb_file.stem.lower()
+                if agent_name in self._entries:
+                    # Still update last_seen from heartbeat timestamp
+                    try:
+                        data = json.loads(hb_file.read_text(encoding="utf-8"))
+                        ts = data.get("timestamp", "")
+                        if ts:
+                            self._entries[agent_name].last_seen = ts
+                    except Exception:
+                        pass
+                    continue
+
+                try:
+                    data = json.loads(hb_file.read_text(encoding="utf-8"))
+                    # Default Syncthing outbox path for this peer
+                    outbox = self._home / "sync" / "comms" / "outbox" / agent_name
+                    entry = DirectoryEntry(
+                        name=agent_name,
+                        address=str(outbox),
+                        transport="syncthing",
+                        fingerprint=data.get("fingerprint", ""),
+                        last_seen=data.get("timestamp", datetime.now(timezone.utc).isoformat()),
+                    )
+                    self._entries[agent_name] = entry
+                    added.append(entry)
+                    logger.info("Auto-discovered '%s' from heartbeat", agent_name)
+                except Exception as exc:
+                    logger.debug("Cannot parse heartbeat %s: %s", hb_file.name, exc)
+
+        # 2. Scan Syncthing outbox dirs
+        outbox_root = self._home / "sync" / "comms" / "outbox"
+        if outbox_root.exists():
+            for peer_dir in sorted(outbox_root.iterdir()):
+                if not peer_dir.is_dir():
+                    continue
+                agent_name = peer_dir.name.lower()
+                if agent_name in self._entries:
+                    continue
+                entry = DirectoryEntry(
+                    name=agent_name,
+                    address=str(peer_dir),
+                    transport="syncthing",
+                )
+                self._entries[agent_name] = entry
+                added.append(entry)
+                logger.info("Auto-discovered '%s' from outbox", agent_name)
+
+        if added:
+            self._save()
+
+        return added
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _ensure_loaded(self) -> None:
+        """Load from disk on first access."""
+        if not self._loaded:
+            self.load()
+
+    def _save(self) -> None:
+        """Atomically serialize the directory to YAML."""
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+
+        data: dict[str, dict] = {}
+        for name, entry in sorted(self._entries.items()):
+            row: dict = {
+                "address": entry.address,
+                "transport": entry.transport,
+            }
+            if entry.fingerprint:
+                row["fingerprint"] = entry.fingerprint
+            if entry.last_seen:
+                row["last_seen"] = entry.last_seen
+            data[name] = row
+
+        tmp = self._path.with_suffix(".yaml.tmp")
+        tmp.write_text(yaml.dump(data, default_flow_style=False), encoding="utf-8")
+        tmp.rename(self._path)

package/src/skcapstone/peers.py

@@ -0,0 +1,329 @@
+"""
+Sovereign peer management — the other half of P2P discovery.
+
+whoami exports your identity card. This module imports someone
+else's card and registers them as a peer in the SKComm keystore.
+The two together form the complete P2P discovery loop.
+
+Flow:
+    1. Agent A runs: skcapstone whoami --export card.json
+    2. Agent A shares card.json with Agent B (USB, chat, email, QR)
+    3. Agent B runs: skcapstone peer add --card card.json
+    4. Agent B can now send encrypted messages to Agent A
+
+Peer data is stored at:
+    ~/.skcomm/peers/<name>.yml     — SKComm peer config
+    ~/.skcapstone/peers/<name>.json — Extended peer metadata
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+import yaml
+from pydantic import BaseModel, Field
+
+from . import SHARED_ROOT
+
+logger = logging.getLogger("skcapstone.peers")
+
+
+class PeerRecord(BaseModel):
+    """A known peer agent.
+
+    Attributes:
+        name: Peer display name.
+        fingerprint: CapAuth PGP fingerprint.
+        public_key: ASCII-armored PGP public key.
+        entity_type: human, ai, or organization.
+        handle: CapAuth identity handle.
+        email: Contact email.
+        capabilities: What this peer can do.
+        contact_uris: How to reach this peer.
+        trust_level: verified, trusted, sovereign, or unknown.
+        added_at: When the peer was added.
+        last_seen: Last known activity.
+        source: How we learned about this peer (card, discovery, manual).
+    """
+
+    name: str
+    fingerprint: str = ""
+    public_key: str = ""
+    entity_type: str = "unknown"
+    handle: str = ""
+    email: str = ""
+    capabilities: list[str] = Field(default_factory=list)
+    contact_uris: list[str] = Field(default_factory=list)
+    trust_level: str = "unknown"
+    added_at: str = Field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+    last_seen: Optional[str] = None
+    source: str = "manual"
+
+
+def add_peer_from_card(
+    card_path: Path,
+    skcapstone_home: Optional[Path] = None,
+    skcomm_home: Optional[Path] = None,
+) -> PeerRecord:
+    """Import a peer from a whoami identity card.
+
+    Reads the card JSON, creates peer records in both skcapstone
+    and skcomm directories, and writes the public key for SKComm
+    encryption.
+
+    Args:
+        card_path: Path to the exported card.json.
+        skcapstone_home: Override skcapstone home. Defaults to ~/.skcapstone/.
+        skcomm_home: Override skcomm home. Defaults to ~/.skcomm/.
+
+    Returns:
+        PeerRecord: The registered peer.
+
+    Raises:
+        FileNotFoundError: If the card file doesn't exist.
+        ValueError: If the card is missing required fields.
+    """
+    card_path = Path(card_path)
+    if not card_path.exists():
+        raise FileNotFoundError(f"Card not found: {card_path}")
+
+    try:
+        card_data = json.loads(card_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid card JSON: {exc}") from exc
+
+    name = card_data.get("name", "").strip()
+    if not name:
+        raise ValueError("Card is missing a 'name' field")
+
+    peer = PeerRecord(
+        name=name,
+        fingerprint=card_data.get("fingerprint", ""),
+        public_key=card_data.get("public_key", ""),
+        entity_type=card_data.get("entity_type", "unknown"),
+        handle=card_data.get("handle", ""),
+        email=card_data.get("email", ""),
+        capabilities=card_data.get("capabilities", []),
+        contact_uris=card_data.get("contact_uris", []),
+        trust_level="verified",
+        source="card",
+    )
+
+    sk_home = skcapstone_home or Path(SHARED_ROOT).expanduser()
+    sc_home = skcomm_home or Path.home() / ".skcomm"
+
+    _save_skcapstone_peer(sk_home, peer)
+    _save_skcomm_peer(sc_home, peer)
+
+    logger.info("Added peer '%s' (fingerprint: %s)", name, peer.fingerprint[:16])
+    return peer
+
+
+def add_peer_manual(
+    name: str,
+    fingerprint: str = "",
+    public_key_path: Optional[Path] = None,
+    email: str = "",
+    skcapstone_home: Optional[Path] = None,
+    skcomm_home: Optional[Path] = None,
+) -> PeerRecord:
+    """Add a peer manually by name and optional key file.
+
+    Args:
+        name: Peer display name.
+        fingerprint: PGP fingerprint (optional).
+        public_key_path: Path to a .asc public key file (optional).
+        email: Contact email (optional).
+        skcapstone_home: Override skcapstone home.
+        skcomm_home: Override skcomm home.
+
+    Returns:
+        PeerRecord: The registered peer.
+    """
+    public_key = ""
+    if public_key_path and Path(public_key_path).exists():
+        public_key = Path(public_key_path).read_text(encoding="utf-8").strip()
+
+    peer = PeerRecord(
+        name=name,
+        fingerprint=fingerprint,
+        public_key=public_key,
+        email=email,
+        source="manual",
+        trust_level="verified" if public_key else "unknown",
+    )
+
+    sk_home = skcapstone_home or Path(SHARED_ROOT).expanduser()
+    sc_home = skcomm_home or Path.home() / ".skcomm"
+
+    _save_skcapstone_peer(sk_home, peer)
+    _save_skcomm_peer(sc_home, peer)
+
+    return peer
+
+
+def list_peers(
+    skcapstone_home: Optional[Path] = None,
+) -> list[PeerRecord]:
+    """List all known peers.
+
+    Args:
+        skcapstone_home: Override skcapstone home.
+
+    Returns:
+        list[PeerRecord]: All registered peers.
+    """
+    sk_home = skcapstone_home or Path(SHARED_ROOT).expanduser()
+    peers_dir = sk_home / "peers"
+    if not peers_dir.exists():
+        return []
+
+    peers = []
+    for f in sorted(peers_dir.glob("*.json")):
+        try:
+            data = json.loads(f.read_text(encoding="utf-8"))
+            peers.append(PeerRecord.model_validate(data))
+        except (json.JSONDecodeError, Exception):
+            continue
+
+    return peers
+
+
+def get_peer(
+    name: str,
+    skcapstone_home: Optional[Path] = None,
+) -> Optional[PeerRecord]:
+    """Get a specific peer by name.
+
+    Args:
+        name: Peer name to look up.
+        skcapstone_home: Override skcapstone home.
+
+    Returns:
+        PeerRecord or None if not found.
+    """
+    sk_home = skcapstone_home or Path(SHARED_ROOT).expanduser()
+    peer_file = sk_home / "peers" / f"{_safe_filename(name)}.json"
+    if not peer_file.exists():
+        return None
+
+    try:
+        data = json.loads(peer_file.read_text(encoding="utf-8"))
+        return PeerRecord.model_validate(data)
+    except (json.JSONDecodeError, Exception):
+        return None
+
+
+def remove_peer(
+    name: str,
+    skcapstone_home: Optional[Path] = None,
+    skcomm_home: Optional[Path] = None,
+) -> bool:
+    """Remove a peer from both skcapstone and skcomm registries.
+
+    Args:
+        name: Peer name to remove.
+        skcapstone_home: Override skcapstone home.
+        skcomm_home: Override skcomm home.
+
+    Returns:
+        bool: True if the peer was found and removed.
+    """
+    sk_home = skcapstone_home or Path(SHARED_ROOT).expanduser()
+    sc_home = skcomm_home or Path.home() / ".skcomm"
+    safe = _safe_filename(name)
+    removed = False
+
+    sk_file = sk_home / "peers" / f"{safe}.json"
+    if sk_file.exists():
+        sk_file.unlink()
+        removed = True
+
+    sc_file = sc_home / "peers" / f"{safe}.yml"
+    if sc_file.exists():
+        sc_file.unlink()
+        removed = True
+
+    sc_key = sc_home / "peers" / f"{safe}.pub.asc"
+    if sc_key.exists():
+        sc_key.unlink()
+
+    logger.info("Removed peer '%s'", name)
+    return removed
+
+
+def _save_skcapstone_peer(home: Path, peer: PeerRecord) -> Path:
+    """Save peer record to skcapstone peers directory.
+
+    Args:
+        home: skcapstone home directory.
+        peer: Peer to save.
+
+    Returns:
+        Path: Written file path.
+    """
+    peers_dir = home / "peers"
+    peers_dir.mkdir(parents=True, exist_ok=True)
+
+    path = peers_dir / f"{_safe_filename(peer.name)}.json"
+    path.write_text(peer.model_dump_json(indent=2), encoding="utf-8")
+    return path
+
+
+def _save_skcomm_peer(home: Path, peer: PeerRecord) -> Path:
+    """Save peer to SKComm peers directory (YAML + public key).
+
+    Creates the YAML config that SKComm's KeyStore reads, and
+    writes the public key as a separate .asc file.
+
+    Args:
+        home: skcomm home directory.
+        peer: Peer to save.
+
+    Returns:
+        Path: Written YAML file path.
+    """
+    peers_dir = home / "peers"
+    peers_dir.mkdir(parents=True, exist_ok=True)
+
+    safe = _safe_filename(peer.name)
+
+    if peer.public_key:
+        key_path = peers_dir / f"{safe}.pub.asc"
+        key_path.write_text(peer.public_key, encoding="utf-8")
+        pubkey_ref = str(key_path)
+    else:
+        pubkey_ref = ""
+
+    peer_yml = {
+        "name": peer.name,
+        "fingerprint": peer.fingerprint,
+        "public_key": pubkey_ref,
+        "email": peer.email,
+        "trust_level": peer.trust_level,
+        "added_at": peer.added_at,
+    }
+
+    path = peers_dir / f"{safe}.yml"
+    path.write_text(yaml.dump(peer_yml, default_flow_style=False), encoding="utf-8")
+    return path
+
+
+def _safe_filename(name: str) -> str:
+    """Convert a peer name to a safe filename.
+
+    Args:
+        name: Peer display name.
+
+    Returns:
+        str: Filesystem-safe version of the name.
+    """
+    safe = name.lower().strip().replace(" ", "-")
+    safe = "".join(c for c in safe if c.isalnum() or c in "-_.")
+    return safe or "unnamed"