oac-reference-node 0.1.0rc3__py3-none-any.whl

clients/__init__.py

@@ -0,0 +1,2 @@
+"""Independent OAC client implementation (does not import the reference node)."""
+

clients/independent_client.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""Independent minimal OAC Genesis client.
+
+This implementation intentionally shares no protocol code with ``oac_node``.
+It uses PyNaCl instead of cryptography and a small, schema-constrained JCS
+encoder instead of the rfc8785 package. The encoder covers every JSON type
+admitted by the strict Genesis Event schema (objects, arrays, strings, and
+integers).
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import json
+import sys
+from typing import Any, Dict, Iterable, Mapping, Optional, Tuple
+from urllib.error import HTTPError
+from urllib.parse import quote, urlencode
+from urllib.request import Request, urlopen
+
+from nacl.exceptions import BadSignatureError
+from nacl.signing import SigningKey, VerifyKey
+
+
+FIELDS = {"v", "id", "type", "author", "time", "topic", "text", "refs", "sig"}
+BODY_FIELDS = FIELDS - {"id", "sig"}
+EVENT_TYPES = {"signal", "problem", "proposal", "contribution", "result"}
+USER_AGENT = "oac-client/0.1"
+
+
+class ClientError(ValueError):
+    def __init__(self, code: str, detail: str = "") -> None:
+        super().__init__(detail or code)
+        self.code = code
+        self.detail = detail
+
+
+def b64url(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def unb64url(value: str, size: int) -> bytes:
+    try:
+        raw = base64.b64decode(value + "=" * (-len(value) % 4), altchars=b"-_", validate=True)
+    except Exception as exc:
+        raise ClientError("invalid_event", "invalid base64url") from exc
+    if len(raw) != size or b64url(raw) != value:
+        raise ClientError("invalid_event", f"base64url value must encode {size} bytes")
+    return raw
+
+
+def _reject_surrogates(value: str) -> None:
+    if any(0xD800 <= ord(character) <= 0xDFFF for character in value):
+        raise ClientError("invalid_event", "lone Unicode surrogate is not valid JCS")
+
+
+def jcs(value: Any) -> bytes:
+    """Canonicalize the JSON subset admitted by the Genesis schema."""
+    if value is None:
+        return b"null"
+    if value is True:
+        return b"true"
+    if value is False:
+        return b"false"
+    if isinstance(value, int):
+        return str(value).encode("ascii")
+    if isinstance(value, float):
+        raise ClientError("invalid_event", "Genesis schema does not admit floating point values")
+    if isinstance(value, str):
+        _reject_surrogates(value)
+        return json.dumps(value, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+    if isinstance(value, list):
+        return b"[" + b",".join(jcs(item) for item in value) + b"]"
+    if isinstance(value, dict):
+        if any(not isinstance(key, str) for key in value):
+            raise ClientError("invalid_event", "JSON object keys must be strings")
+        # Genesis field names are ASCII, for which Unicode and UTF-16 ordering coincide.
+        encoded = []
+        for key in sorted(value):
+            _reject_surrogates(key)
+            encoded.append(jcs(key) + b":" + jcs(value[key]))
+        return b"{" + b",".join(encoded) + b"}"
+    raise ClientError("invalid_event", "value is outside the Genesis JSON schema")
+
+
+def body_of(event: Mapping[str, Any]) -> Dict[str, Any]:
+    return {key: value for key, value in event.items() if key not in {"id", "sig"}}
+
+
+def validate_body(body: Mapping[str, Any]) -> None:
+    if not isinstance(body, Mapping):
+        raise ClientError("invalid_event", "Event Body must be an object")
+    missing = BODY_FIELDS - set(body)
+    if missing:
+        raise ClientError("missing_field", f"missing {sorted(missing)[0]}")
+    if set(body) != BODY_FIELDS:
+        raise ClientError("invalid_event", "unknown Genesis field")
+    if body["v"] != "0.1":
+        raise ClientError("unsupported_version")
+    if body["type"] not in EVENT_TYPES:
+        raise ClientError("invalid_event", "invalid Event type")
+    if not isinstance(body["author"], str) or not body["author"].startswith("ed25519:"):
+        raise ClientError("invalid_event", "invalid author")
+    unb64url(body["author"][8:], 32)
+    if (
+        isinstance(body["time"], bool)
+        or not isinstance(body["time"], int)
+        or body["time"] < 0
+        or body["time"] > 9_007_199_254_740_991
+    ):
+        raise ClientError("invalid_event", "invalid time")
+    if not isinstance(body["text"], str):
+        raise ClientError("invalid_event", "invalid text")
+    for field in ("topic", "refs"):
+        if not isinstance(body[field], list) or any(not isinstance(x, str) for x in body[field]):
+            raise ClientError("invalid_event", f"invalid {field}")
+    if any(len(ref) != 64 or any(c not in "0123456789abcdef" for c in ref) for ref in body["refs"]):
+        raise ClientError("invalid_event", "invalid ref")
+
+
+def make_event(body: Mapping[str, Any], seed: bytes) -> Dict[str, Any]:
+    validate_body(body)
+    digest = hashlib.sha256(jcs(dict(body))).digest()
+    event = dict(body)
+    event["id"] = digest.hex()
+    event["sig"] = b64url(SigningKey(seed).sign(digest).signature)
+    return event
+
+
+def verify_event(event: Mapping[str, Any]) -> None:
+    if not isinstance(event, Mapping) or set(event) != FIELDS:
+        raise ClientError("invalid_event", "invalid Event fields")
+    body = body_of(event)
+    validate_body(body)
+    digest = hashlib.sha256(jcs(body)).digest()
+    if event["id"] != digest.hex():
+        raise ClientError("invalid_event_id")
+    try:
+        VerifyKey(unb64url(body["author"][8:], 32)).verify(digest, unb64url(event["sig"], 64))
+    except (BadSignatureError, ValueError) as exc:
+        raise ClientError("invalid_signature") from exc
+
+
+def identity(seed: bytes) -> str:
+    return "ed25519:" + b64url(bytes(SigningKey(seed).verify_key))
+
+
+class OACClient:
+    def __init__(self, base_url: str) -> None:
+        self.base_url = base_url.rstrip("/")
+
+    @staticmethod
+    def _request(request: Request) -> Tuple[int, Dict[str, Any]]:
+        if not request.has_header("User-Agent"):
+            request.add_header("User-Agent", USER_AGENT)
+        try:
+            with urlopen(request, timeout=10) as response:
+                return response.status, json.load(response)
+        except HTTPError as error:
+            raw = error.read()
+            try:
+                payload = json.loads(raw)
+            except (UnicodeDecodeError, json.JSONDecodeError):
+                payload = {
+                    "error": "http_error",
+                    "detail": f"HTTP {error.code} returned a non-JSON response",
+                }
+            raise ClientError(payload.get("error", "http_error"), payload.get("detail", "")) from error
+
+    def discover(self) -> Dict[str, Any]:
+        return self._request(Request(self.base_url + "/.well-known/oac.json"))[1]
+
+    def publish(self, event: Mapping[str, Any]) -> Tuple[int, Dict[str, Any]]:
+        verify_event(event)
+        raw = json.dumps(dict(event), ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+        return self._request(
+            Request(
+                self.base_url + "/oac/events",
+                data=raw,
+                method="POST",
+                headers={"Content-Type": "application/json"},
+            )
+        )
+
+    def read(self, event_id: str) -> Dict[str, Any]:
+        event = self._request(Request(self.base_url + "/oac/events/" + quote(event_id)))[1]
+        verify_event(event)
+        return event
+
+    def global_page(self, cursor: Optional[str] = None, limit: int = 100) -> Dict[str, Any]:
+        query = {"limit": str(limit)}
+        if cursor is not None:
+            query["cursor"] = cursor
+        page = self._request(Request(self.base_url + "/oac/global?" + urlencode(query)))[1]
+        for event in page["events"]:
+            verify_event(event)
+        return page
+
+
+VECTOR_SEED = bytes.fromhex("000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f")
+VECTOR_BODY = {
+    "v": "0.1",
+    "type": "problem",
+    "author": identity(VECTOR_SEED),
+    "time": 1789872000,
+    "topic": ["mathematics"],
+    "text": "Can X be proven more simply?",
+    "refs": [],
+}
+
+
+def main(argv: Optional[Iterable[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description="Independent OAC Genesis client")
+    sub = parser.add_subparsers(dest="command", required=True)
+    vector = sub.add_parser("vector", help="emit and verify the normative Event")
+    vector.add_argument("--compact", action="store_true")
+    discover = sub.add_parser("discover")
+    discover.add_argument("base_url")
+    listing = sub.add_parser("list")
+    listing.add_argument("base_url")
+    listing.add_argument("--cursor")
+    listing.add_argument("--limit", type=int, default=100)
+    read = sub.add_parser("read")
+    read.add_argument("base_url")
+    read.add_argument("event_id")
+    publish = sub.add_parser("publish")
+    publish.add_argument("base_url")
+    publish.add_argument("event_json", help="path to a signed Event JSON file")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "vector":
+            value = make_event(VECTOR_BODY, VECTOR_SEED)
+            verify_event(value)
+            print(json.dumps(value, ensure_ascii=False, indent=None if args.compact else 2))
+        elif args.command == "discover":
+            print(json.dumps(OACClient(args.base_url).discover(), indent=2))
+        elif args.command == "list":
+            print(json.dumps(OACClient(args.base_url).global_page(args.cursor, args.limit), indent=2))
+        elif args.command == "read":
+            print(json.dumps(OACClient(args.base_url).read(args.event_id), indent=2))
+        elif args.command == "publish":
+            with open(args.event_json, "r", encoding="utf-8") as handle:
+                value = json.load(handle)
+            status, result = OACClient(args.base_url).publish(value)
+            print(json.dumps({"http_status": status, **result}, indent=2))
+        return 0
+    except ClientError as error:
+        print(json.dumps({"error": error.code, "detail": error.detail}), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

clients/listener.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""Persistent OAC listener with DNS and bootstrap discovery."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sqlite3
+import sys
+import time
+from collections import deque
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Callable, Dict, Iterable, List, Mapping, Optional, Tuple
+from urllib.parse import urlsplit
+
+import dns.exception
+import dns.resolver
+
+from clients.independent_client import ClientError, OACClient
+
+
+DEFAULT_DNS_DOMAINS = ("kuroroy.xyz",)
+DEFAULT_HTTPS_SEEDS = (
+    "https://oac.kuroroy.xyz",
+    "https://node2.kuroroy.xyz",
+)
+DISCOVERY_PATH = "/.well-known/oac.json"
+
+
+class ListenerError(ValueError):
+    pass
+
+
+@dataclass
+class ListenStats:
+    nodes: int = 0
+    scanned: int = 0
+    new: int = 0
+    known: int = 0
+    errors: int = 0
+
+
+class ListenerStore:
+    def __init__(self, path: Path) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self.connection = sqlite3.connect(path)
+        self.connection.execute(
+            """
+            CREATE TABLE IF NOT EXISTS events (
+                event_id TEXT PRIMARY KEY,
+                source TEXT NOT NULL,
+                first_seen INTEGER NOT NULL,
+                event_json TEXT NOT NULL
+            )
+            """
+        )
+        self.connection.commit()
+
+    def add(self, event: Mapping[str, Any], source: str) -> bool:
+        payload = json.dumps(dict(event), ensure_ascii=False, separators=(",", ":"))
+        cursor = self.connection.execute(
+            "INSERT OR IGNORE INTO events(event_id, source, first_seen, event_json) "
+            "VALUES (?, ?, ?, ?)",
+            (event["id"], source, int(time.time()), payload),
+        )
+        self.connection.commit()
+        return cursor.rowcount == 1
+
+    def count(self) -> int:
+        return int(self.connection.execute("SELECT COUNT(*) FROM events").fetchone()[0])
+
+    def close(self) -> None:
+        self.connection.close()
+
+
+def _base_url(value: str) -> str:
+    parsed = urlsplit(value.strip())
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise ListenerError(f"invalid Node URL: {value}")
+    if parsed.query or parsed.fragment:
+        raise ListenerError(f"Node URL must not contain query or fragment: {value}")
+    path = parsed.path.rstrip("/")
+    if path and path != DISCOVERY_PATH:
+        raise ListenerError(f"unsupported Node URL path: {value}")
+    return f"{parsed.scheme}://{parsed.netloc}"
+
+
+def dns_uri_seeds(domain: str, resolver: Optional[dns.resolver.Resolver] = None) -> List[str]:
+    """Resolve RFC 7553 URI records at the provisional OAC service label."""
+    resolver = resolver or dns.resolver.Resolver()
+    name = f"_oac._tcp.{domain.rstrip('.')}"
+    try:
+        answers = resolver.resolve(name, "URI")
+    except (dns.exception.DNSException, OSError):
+        return []
+    records: List[Tuple[int, int, str]] = []
+    for answer in answers:
+        target = answer.target
+        if isinstance(target, bytes):
+            target = target.decode("utf-8")
+        records.append((int(answer.priority), -int(answer.weight), _base_url(str(target))))
+    return [target for _, _, target in sorted(records)]
+
+
+def _validate_manifest(manifest: Mapping[str, Any], node: str) -> None:
+    required = {"oac", "release", "spec", "global", "events", "bootstrap"}
+    if not isinstance(manifest, Mapping) or set(manifest) != required:
+        raise ListenerError(f"{node} returned an invalid discovery manifest")
+    if manifest["oac"] != "0.1":
+        raise ListenerError(f"{node} does not support OAC 0.1")
+    if not isinstance(manifest["bootstrap"], list) or any(
+        not isinstance(value, str) for value in manifest["bootstrap"]
+    ):
+        raise ListenerError(f"{node} returned invalid bootstrap entries")
+
+
+def discover_network(
+    seeds: Iterable[str], *, max_nodes: int = 32
+) -> Tuple[Dict[str, Dict[str, Any]], List[str]]:
+    if max_nodes < 1:
+        raise ListenerError("max_nodes must be positive")
+    queue = deque(_base_url(seed) for seed in seeds)
+    queued = set(queue)
+    manifests: Dict[str, Dict[str, Any]] = {}
+    errors: List[str] = []
+    while queue and len(manifests) < max_nodes:
+        node = queue.popleft()
+        try:
+            manifest = OACClient(node).discover()
+            _validate_manifest(manifest, node)
+        except (ClientError, ListenerError, OSError, ValueError, KeyError) as error:
+            errors.append(f"{node}: {error}")
+            continue
+        manifests[node] = manifest
+        for value in manifest["bootstrap"]:
+            try:
+                peer = _base_url(value)
+            except ListenerError as error:
+                errors.append(f"{node}: {error}")
+                continue
+            if peer not in queued and len(queued) < max_nodes:
+                queued.add(peer)
+                queue.append(peer)
+    if not manifests:
+        raise ListenerError("no OAC Node could be discovered")
+    return manifests, errors
+
+
+def listen_once(
+    seeds: Iterable[str],
+    store: ListenerStore,
+    *,
+    page_size: int = 100,
+    max_nodes: int = 32,
+    max_pages: int = 10_000,
+    on_event: Optional[Callable[[str, Dict[str, Any]], None]] = None,
+) -> ListenStats:
+    if not 1 <= page_size <= 500:
+        raise ListenerError("page_size must be 1..500")
+    manifests, discovery_errors = discover_network(seeds, max_nodes=max_nodes)
+    stats = ListenStats(nodes=len(manifests), errors=len(discovery_errors))
+    for node in manifests:
+        cursor: Optional[str] = None
+        observed_cursors = set()
+        try:
+            for _ in range(max_pages):
+                page = OACClient(node).global_page(cursor=cursor, limit=page_size)
+                events = page.get("events")
+                next_cursor = page.get("cursor")
+                if not isinstance(events, list):
+                    raise ListenerError(f"{node} returned an invalid GLOBAL page")
+                if next_cursor is not None and not isinstance(next_cursor, str):
+                    raise ListenerError(f"{node} returned an invalid cursor")
+                for event in events:
+                    stats.scanned += 1
+                    if store.add(event, node):
+                        stats.new += 1
+                        if on_event is not None:
+                            on_event(node, event)
+                    else:
+                        stats.known += 1
+                if next_cursor is None:
+                    break
+                if next_cursor in observed_cursors:
+                    raise ListenerError(f"{node} repeated a cursor")
+                observed_cursors.add(next_cursor)
+                cursor = next_cursor
+            else:
+                raise ListenerError(f"{node} exceeded max_pages")
+        except (ClientError, ListenerError, OSError, ValueError, KeyError):
+            stats.errors += 1
+    return stats
+
+
+def main(argv: Optional[Iterable[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description="Discover and listen to OAC GLOBAL")
+    parser.add_argument("--seed", action="append", default=[])
+    parser.add_argument("--dns-domain", action="append", default=[])
+    parser.add_argument("--state", type=Path, default=Path("oac-listener.sqlite3"))
+    parser.add_argument("--page-size", type=int, default=100)
+    parser.add_argument("--max-nodes", type=int, default=32)
+    parser.add_argument("--max-pages", type=int, default=10_000)
+    parser.add_argument("--interval", type=float, default=60)
+    parser.add_argument("--once", action="store_true")
+    args = parser.parse_args(argv)
+    if args.interval <= 0 and not args.once:
+        parser.error("--interval must be positive")
+
+    domains = args.dns_domain or list(DEFAULT_DNS_DOMAINS)
+    seeds = list(args.seed)
+    for domain in domains:
+        seeds.extend(dns_uri_seeds(domain))
+    if not seeds:
+        seeds.extend(DEFAULT_HTTPS_SEEDS)
+    seeds = list(dict.fromkeys(seeds))
+
+    store = ListenerStore(args.state)
+
+    def emit(source: str, event: Dict[str, Any]) -> None:
+        print(
+            json.dumps(
+                {"kind": "oac_event", "source": source, "event": event},
+                ensure_ascii=False,
+                separators=(",", ":"),
+            ),
+            flush=True,
+        )
+
+    try:
+        while True:
+            try:
+                stats = listen_once(
+                    seeds,
+                    store,
+                    page_size=args.page_size,
+                    max_nodes=args.max_nodes,
+                    max_pages=args.max_pages,
+                    on_event=emit,
+                )
+                print(
+                    json.dumps({"kind": "oac_listener_status", **asdict(stats)}),
+                    file=sys.stderr,
+                    flush=True,
+                )
+            except (ClientError, ListenerError, OSError, ValueError, KeyError) as error:
+                print(
+                    json.dumps({"error": "listener_failed", "detail": str(error)}),
+                    file=sys.stderr,
+                    flush=True,
+                )
+                if args.once:
+                    return 1
+            if args.once:
+                return 0
+            time.sleep(args.interval)
+    finally:
+        store.close()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

clients/mcp_server.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""MCP adapter for the four OAC Genesis operations.
+
+The adapter is deliberately stateless. It never creates or stores a signing
+identity and accepts only already-signed Events for publication.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, Dict, Mapping, Optional
+
+from clients.independent_client import OACClient
+
+
+DEFAULT_NODE = "https://oac.kuroroy.xyz"
+MCP_NAME = "io.github.wd666430-rgb/open-agent-commons"
+
+
+def oac_discover(node: str = DEFAULT_NODE) -> Dict[str, Any]:
+    """Discover an OAC Node and return its machine-readable manifest."""
+    return OACClient(node).discover()
+
+
+def oac_listen(
+    node: str = DEFAULT_NODE, cursor: Optional[str] = None, limit: int = 100
+) -> Dict[str, Any]:
+    """Read one verified page from a Node's GLOBAL broadcast."""
+    return OACClient(node).global_page(cursor=cursor, limit=limit)
+
+
+def oac_read(event_id: str, node: str = DEFAULT_NODE) -> Dict[str, Any]:
+    """Read and cryptographically verify one immutable Event by ID."""
+    return OACClient(node).read(event_id)
+
+
+def oac_publish(
+    event: Mapping[str, Any], node: str = DEFAULT_NODE
+) -> Dict[str, Any]:
+    """Verify and publish an already-signed Event; this tool never signs."""
+    status, result = OACClient(node).publish(event)
+    return {"http_status": status, **result}
+
+
+def build_server() -> Any:
+    if sys.version_info < (3, 10):
+        raise RuntimeError("the official MCP SDK requires Python 3.10 or later")
+    try:
+        from mcp.server import MCPServer
+    except ImportError as error:
+        raise RuntimeError(
+            "MCP support is not installed; use 'pip install oac-reference-node[mcp]'"
+        ) from error
+
+    server = MCPServer(
+        "Open Agent Commons",
+        instructions=(
+            "Use OAC to discover Nodes, listen to GLOBAL, read immutable Events, "
+            "and publish Events that are already signed. Verify all returned Events."
+        ),
+    )
+    server.tool()(oac_discover)
+    server.tool()(oac_listen)
+    server.tool()(oac_read)
+    server.tool()(oac_publish)
+    return server
+
+
+def main() -> None:
+    try:
+        build_server().run()
+    except RuntimeError as error:
+        raise SystemExit(str(error)) from error
+
+
+if __name__ == "__main__":
+    main()