sm-divergence 0.7.0__py3-none-any.whl

sm_divergence/__init__.py

@@ -0,0 +1,119 @@
+"""sm-divergence — catch a cheating registry by corroboration.
+
+A registry that agents discover each other through can lie by omission (hide a
+record), by tampering (serve a false endpoint), or by equivocation (different
+answers to different clients). No signature on a single record can prove what a
+registry chose not to serve. With two or more registries, this library asks all
+of them the same questions and reports any disagreement: omission, endpoint, or
+key-identity (DID) divergence.
+
+Layout:
+  - ``sm-resolver`` (dependency) — the source-agnostic kernel: ``Resolver[T]``,
+    the ``View`` contract, ``diff_views``, ``Corroborator``, ``Finding``.
+  - ``sm_divergence.discovery`` — the registry-integrity layer: ``RecordView``
+    plus the ``HttpByIdResolver`` (NEST) and ``NandaIndexV2Resolver`` adapters.
+
+Quick start::
+
+    import asyncio
+    from sm_divergence import check_once
+
+    findings = asyncio.run(check_once(
+        ["https://registry-a.example", "https://registry-b.example"],
+        ["agent-1", "agent-2"],
+    ))
+    for f in findings:
+        print(f.kind, f.agent_id, f.detail)
+"""
+
+from sm_resolver import OMISSION, Corroborator, Finding, OnFinding, Resolver, Status, View, ViewT, diff_views
+
+from .detector import DivergenceDetector, check_once
+from .discovery import (
+    DEFAULT_PATH,
+    DID,
+    ENDPOINT,
+    HttpByIdResolver,
+    NandaIndexV2Resolver,
+    RecordAdapter,
+    RecordView,
+    binds_by_did,
+    default_adapter,
+    fetch_view,
+    identity_locator,
+    looks_absent,
+    signed_record_adapter,
+    verified_did,
+)
+from .identity import (
+    KEY,
+    AliasClosureResolver,
+    DescriptionReconciliation,
+    DidKeyResolver,
+    DidView,
+    DidWebResolver,
+    HttpDescriptionResolver,
+    SelfDescription,
+    UniversalResolverResolver,
+    binds_by_key,
+    build_self_description,
+    corroborate_descriptions,
+    did_web_url,
+    identity_did,
+    key_from_did_document,
+    key_from_did_key,
+    reconcile_descriptions,
+    signed_alias_for,
+    verified_descriptions,
+    verify_self_description,
+)
+
+__version__ = "0.7.0"
+
+__all__ = [
+    "DEFAULT_PATH",
+    "DID",
+    "ENDPOINT",
+    "KEY",
+    "OMISSION",
+    "AliasClosureResolver",
+    "Corroborator",
+    "DescriptionReconciliation",
+    "DidKeyResolver",
+    "DidView",
+    "DidWebResolver",
+    "DivergenceDetector",
+    "Finding",
+    "HttpByIdResolver",
+    "HttpDescriptionResolver",
+    "NandaIndexV2Resolver",
+    "OnFinding",
+    "RecordAdapter",
+    "RecordView",
+    "Resolver",
+    "SelfDescription",
+    "Status",
+    "UniversalResolverResolver",
+    "View",
+    "ViewT",
+    "binds_by_did",
+    "binds_by_key",
+    "build_self_description",
+    "check_once",
+    "corroborate_descriptions",
+    "default_adapter",
+    "diff_views",
+    "did_web_url",
+    "fetch_view",
+    "identity_did",
+    "identity_locator",
+    "key_from_did_document",
+    "key_from_did_key",
+    "looks_absent",
+    "reconcile_descriptions",
+    "signed_alias_for",
+    "signed_record_adapter",
+    "verified_descriptions",
+    "verified_did",
+    "verify_self_description",
+]

sm_divergence/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

sm_divergence/_signing.py

@@ -0,0 +1,88 @@
+"""Shared Ed25519 / ``did:key`` / JCS primitives — the self-certifying substrate.
+
+Used by the discovery layer's verified-DID adapter and the identity layer's
+self-description. Behind the ``attestation`` extra (``cryptography``, ``base58``,
+``jcs``); every function raises a clear error if the extra is absent, so the base
+install still runs the crypto-free checks (omission, endpoint, multibase key).
+
+A ``did:key`` *is* the public key, so everything here verifies offline — no
+network, no external trust.
+"""
+
+from __future__ import annotations
+
+import base64
+from collections.abc import Mapping
+from typing import Any
+
+try:
+    import base58
+    import jcs  # type: ignore[import-untyped]
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+    from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+
+    _HAVE_CRYPTO = True
+except ImportError:  # pragma: no cover - exercised only without the extra
+    _HAVE_CRYPTO = False
+
+_ED25519_MULTICODEC = b"\xed\x01"
+_EXTRA = "requires the 'attestation' extra: pip install sm-divergence[attestation]"
+
+
+def _require() -> None:
+    if not _HAVE_CRYPTO:
+        raise RuntimeError(_EXTRA)
+
+
+def canonical(obj: Mapping[str, Any]) -> bytes:
+    """RFC 8785 (JCS) canonical bytes — byte-identical for signer and verifier."""
+    _require()
+    result: bytes = jcs.canonicalize(obj)
+    return result
+
+
+def pubkey_from_did_key(did: str) -> bytes | None:
+    """The 32-byte Ed25519 public key a ``did:key`` encodes, or None."""
+    _require()
+    if not did.startswith("did:key:z"):
+        return None
+    try:
+        raw = base58.b58decode(did[len("did:key:z") :])
+    except Exception:
+        return None
+    if len(raw) != 34 or raw[:2] != _ED25519_MULTICODEC:
+        return None
+    return bytes(raw[2:])
+
+
+def did_key_from_pubkey(pubkey: bytes) -> str:
+    """The ``did:key`` for an Ed25519 public key (multicodec + base58btc)."""
+    _require()
+    encoded: str = base58.b58encode(_ED25519_MULTICODEC + pubkey).decode()
+    return "did:key:z" + encoded
+
+
+def public_from_private(private_key: bytes) -> bytes:
+    """The 32-byte Ed25519 public key for a 32-byte private key."""
+    _require()
+    pub: bytes = (
+        Ed25519PrivateKey.from_private_bytes(private_key).public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)
+    )
+    return pub
+
+
+def sign(private_key: bytes, message: bytes) -> str:
+    """Base64 Ed25519 signature over ``message`` with a 32-byte private key."""
+    _require()
+    return base64.b64encode(Ed25519PrivateKey.from_private_bytes(private_key).sign(message)).decode()
+
+
+def verify(pubkey: bytes, message: bytes, sig_b64: str) -> bool:
+    """True iff ``sig_b64`` is a valid Ed25519 signature of ``message``. Never raises."""
+    _require()
+    try:
+        Ed25519PublicKey.from_public_bytes(pubkey).verify(base64.b64decode(sig_b64), message)
+        return True
+    except (InvalidSignature, Exception):
+        return False

sm_divergence/cli.py

@@ -0,0 +1,109 @@
+"""``python -m sm_divergence`` — one-shot divergence check for cron / CI.
+
+    python -m sm_divergence check \
+        --registry https://registry-a.example \
+        --registry https://registry-b.example \
+        --watch agent-1 --watch agent-2
+
+Exit code is 0 when the registries agree, 2 when any divergence is found (so a
+cron or CI step fails loudly), and 1 on a usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from collections.abc import Sequence
+
+from sm_resolver import Finding, Resolver
+
+from .detector import check_once
+from .discovery import DEFAULT_PATH, NandaIndexV2Resolver, RecordAdapter, RecordView, default_adapter
+
+EXIT_OK = 0
+EXIT_USAGE = 1
+EXIT_DIVERGENCE = 2
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="sm_divergence", description="Catch a cheating registry by corroboration.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    check = sub.add_parser("check", help="Compare registries for a set of ids.")
+    check.add_argument(
+        "--registry",
+        action="append",
+        default=[],
+        metavar="URL",
+        help="NEST-style by-id registry base URL (repeatable).",
+    )
+    check.add_argument(
+        "--nanda-index",
+        action="append",
+        default=[],
+        metavar="URL",
+        help="NANDA Index v2 base URL — two-hop resolve (repeatable). Watch ids are used as locators.",
+    )
+    check.add_argument("--watch", action="append", default=[], metavar="ID", help="Agent id to compare (repeatable).")
+    check.add_argument(
+        "--path", default=DEFAULT_PATH, help=f"By-id path template for --registry (default: {DEFAULT_PATH})."
+    )
+    check.add_argument("--timeout", type=float, default=10.0, help="Per-request timeout seconds (default: 10).")
+    check.add_argument(
+        "--attestation",
+        action="store_true",
+        help="Also compare verified DIDs from signed records (needs the 'attestation' extra).",
+    )
+    check.add_argument("--json", action="store_true", help="Emit findings as JSON.")
+    return parser
+
+
+def _format_text(findings: list[Finding]) -> str:
+    if not findings:
+        return "OK — registries agree on all watched ids."
+    lines = [f"DIVERGENCE — {len(findings)} finding(s):"]
+    for f in findings:
+        lines.append(f"  [{f.kind}] {f.agent_id}: {json.dumps(f.detail, sort_keys=True)}")
+    return "\n".join(lines)
+
+
+async def _run_check(args: argparse.Namespace) -> int:
+    watch = [w for w in args.watch if w]
+    http_registries = [r for r in args.registry if r]
+    index_urls = [u for u in args.nanda_index if u]
+    if len(http_registries) + len(index_urls) < 2:
+        print("error: need at least two registries (--registry / --nanda-index) to corroborate", file=sys.stderr)
+        return EXIT_USAGE
+    if not watch:
+        print("error: need at least one --watch id", file=sys.stderr)
+        return EXIT_USAGE
+
+    adapter: RecordAdapter = default_adapter
+    if args.attestation:
+        from .discovery import signed_record_adapter
+
+        adapter = signed_record_adapter()
+
+    registries: list[str | Resolver[RecordView]] = list(http_registries)
+    registries += [NandaIndexV2Resolver(u, adapter=adapter, timeout=args.timeout) for u in index_urls]
+
+    findings = await check_once(registries, watch, adapter=adapter, path=args.path, timeout=args.timeout)
+
+    if args.json:
+        print(json.dumps([f.to_dict() for f in findings], sort_keys=True, indent=2))
+    else:
+        print(_format_text(findings))
+    return EXIT_DIVERGENCE if findings else EXIT_OK
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    if args.command == "check":
+        return asyncio.run(_run_check(args))
+    return EXIT_USAGE
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sm_divergence/detector.py

@@ -0,0 +1,61 @@
+"""The discovery-layer product: a ``Corroborator`` specialized to registries.
+
+``DivergenceDetector`` is a thin convenience over the core ``Corroborator`` — it
+accepts bare registry URLs (wrapping them in ``HttpByIdResolver``) alongside
+``Resolver`` instances of any format, so ``check_once(["https://a", "https://b"])``
+keeps working while heterogeneous resolvers mix freely. The generic orchestration
+lives in ``sm-resolver`` (the kernel); this file only adds the discovery defaults.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from sm_resolver import Corroborator, Finding, OnFinding, Resolver
+
+from .discovery import DEFAULT_PATH, HttpByIdResolver, RecordAdapter, RecordView, default_adapter
+
+__all__ = ["DivergenceDetector", "OnFinding", "check_once"]
+
+
+class DivergenceDetector(Corroborator[RecordView]):
+    """Cross-registry divergence detector.
+
+    Point it at two or more registries — each a base URL (wrapped in an
+    ``HttpByIdResolver`` with the shared ``adapter``/``path``) or a ``Resolver``
+    instance for a registry of a different format (e.g. ``NandaIndexV2Resolver``).
+    Registries of different formats mix freely; each normalizes to a
+    ``RecordView`` so the diff treats them uniformly. Fewer than two → no-op.
+    """
+
+    def __init__(
+        self,
+        registries: Iterable[str | Resolver[RecordView]],
+        *,
+        adapter: RecordAdapter = default_adapter,
+        path: str = DEFAULT_PATH,
+        on_finding: OnFinding | None = None,
+        timeout: float = 10.0,
+    ) -> None:
+        resolvers: list[Resolver[RecordView]] = [
+            HttpByIdResolver(r, adapter=adapter, path=path, timeout=timeout) if isinstance(r, str) else r
+            for r in registries
+        ]
+        super().__init__(resolvers, on_finding=on_finding)
+
+    @property
+    def registries(self) -> list[str]:
+        """The registry labels being compared (back-compat + introspection)."""
+        return self.labels
+
+
+async def check_once(
+    registries: Iterable[str | Resolver[RecordView]],
+    watch_ids: Iterable[str],
+    *,
+    adapter: RecordAdapter = default_adapter,
+    path: str = DEFAULT_PATH,
+    timeout: float = 10.0,
+) -> list[Finding]:
+    """One-shot convenience: build a detector and run a single check."""
+    return await DivergenceDetector(registries, adapter=adapter, path=path, timeout=timeout).check(watch_ids)

sm_divergence/discovery/__init__.py

@@ -0,0 +1,32 @@
+"""sm-divergence discovery layer — the registry-integrity instantiation.
+
+Supplies the discovery view type (``RecordView``) and the format resolvers
+(``HttpByIdResolver`` for NEST-style by-id registries, ``NandaIndexV2Resolver``
+for the NANDA Index two-hop resolve), all built on the source-agnostic core.
+Each resolver is a thin adapter; adding another registry format is another file
+here, with no change to the core diff.
+"""
+
+from .attestation import signed_record_adapter, verified_did
+from .client import DEFAULT_PATH, RecordAdapter, default_adapter, fetch_view, looks_absent
+from .closure import binds_by_did
+from .http_by_id import HttpByIdResolver
+from .index_v2 import NandaIndexV2Resolver, identity_locator
+from .views import DID, ENDPOINT, RecordView
+
+__all__ = [
+    "DEFAULT_PATH",
+    "DID",
+    "ENDPOINT",
+    "HttpByIdResolver",
+    "NandaIndexV2Resolver",
+    "RecordAdapter",
+    "RecordView",
+    "binds_by_did",
+    "default_adapter",
+    "fetch_view",
+    "identity_locator",
+    "looks_absent",
+    "signed_record_adapter",
+    "verified_did",
+]

sm_divergence/discovery/attestation.py

@@ -0,0 +1,81 @@
+"""Optional: a record adapter that extracts a *verified* DID.
+
+Endpoint and omission divergence need no crypto. The ``did`` divergence — two
+registries serving records that claim different key identities — only means
+something if each DID was actually proven, so this module verifies a signed,
+self-certifying record before contributing its DID to the comparison.
+
+Reference format (a common self-certifying-record convention, not tied to any
+one registry):
+
+    {
+      "record": { ... , "did": "did:key:z6Mk...", "endpoint": "https://..." },
+      "sig":    "<base64 Ed25519 signature over the JCS-canonical record>"
+    }
+
+The DID is verified against ITSELF: a ``did:key`` encodes the Ed25519 public
+key, so the signature is checked with no external lookup. A record whose
+signature doesn't verify (or whose subject doesn't match) contributes no DID.
+
+Requires the ``attestation`` extra: ``pip install sm-divergence[attestation]``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .. import _signing
+from .client import RecordAdapter
+from .views import RecordView
+
+
+def verified_did(attestation: Any) -> str | None:
+    """The DID of a signed record iff its signature verifies against the key
+    the DID itself encodes; else None. Never raises."""
+    if not isinstance(attestation, dict):
+        return None
+    record = attestation.get("record")
+    sig_b64 = attestation.get("sig")
+    if not isinstance(record, dict) or not isinstance(sig_b64, str) or not sig_b64:
+        return None
+    did = record.get("did")
+    if not isinstance(did, str):
+        return None
+    pub = _signing.pubkey_from_did_key(did)
+    if pub is None:
+        return None
+    if not _signing.verify(pub, _signing.canonical(record), sig_b64):
+        return None
+    return did
+
+
+def signed_record_adapter(
+    endpoint_field: str = "endpoint",
+    attestation_field: str = "attestation",
+    *,
+    require_subject_match: bool = True,
+) -> RecordAdapter:
+    """A ``RecordAdapter`` that maps a registry record to endpoint + VERIFIED DID.
+
+    The DID is taken only from a valid attestation under ``attestation_field``.
+    When ``require_subject_match`` is set (default), the attestation's
+    ``record.agent_id`` must equal the outer record's — a registry can't dress
+    one agent's record in another's valid attestation.
+    """
+
+    def _adapt(record: dict[str, Any]) -> RecordView:
+        ep = record.get(endpoint_field)
+        endpoint = str(ep).rstrip("/") if isinstance(ep, str) and ep else None
+
+        did: str | None = None
+        att = record.get(attestation_field)
+        vdid = verified_did(att) if att is not None else None
+        if vdid is not None:
+            inner = att.get("record", {}) if isinstance(att, dict) else {}
+            subject = inner.get("agent_id")
+            outer = record.get("agent_id")
+            if not require_subject_match or subject is None or outer is None or str(subject) == str(outer):
+                did = vdid
+        return RecordView(endpoint=endpoint, did=did)
+
+    return _adapt

sm_divergence/discovery/client.py

@@ -0,0 +1,73 @@
+"""Fetch one registry's claim about one id over HTTP, reduced to a RecordView.
+
+The HTTP path and the record→RecordView mapping are both injectable, so this
+works against any registry that answers a by-id query. The default targets the
+common NEST-style ``GET /api/agents/{id}`` returning JSON with a top-level
+``endpoint``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+from sm_resolver import Status
+
+from .views import RecordView
+
+# Maps a raw registry record (parsed JSON dict) to the discovery view.
+RecordAdapter = Callable[[dict[str, Any]], RecordView]
+
+DEFAULT_PATH = "/api/agents/{id}"
+
+
+def default_adapter(record: dict[str, Any]) -> RecordView:
+    """Read a top-level ``endpoint`` string; no DID (see
+    ``sm_divergence.discovery.attestation`` for a signed-record adapter)."""
+    ep = record.get("endpoint")
+    return RecordView(endpoint=str(ep).rstrip("/") if isinstance(ep, str) and ep else None)
+
+
+def looks_absent(doc: dict[str, Any]) -> bool:
+    """A 200 body that actually means 'not found' — some registries soft-404
+    with ``{"success": false, "error": "... not found"}`` instead of a 404.
+    Shared by every HTTP resolver so soft-404 is classified consistently."""
+    if doc.get("success") is False:
+        return True
+    return "not found" in str(doc.get("error") or "").lower()
+
+
+async def fetch_view(
+    client: httpx.AsyncClient,
+    registry_url: str,
+    agent_id: str,
+    *,
+    adapter: RecordAdapter = default_adapter,
+    path: str = DEFAULT_PATH,
+    timeout: float = 10.0,
+) -> tuple[Status, RecordView | None]:
+    """One registry's claim about one id (``present`` / ``absent`` / ``error``).
+    Never raises."""
+    url = registry_url.rstrip("/") + path.replace("{id}", agent_id)
+    try:
+        resp = await client.get(url, timeout=timeout)
+    except Exception:
+        return "error", None
+    if resp.status_code == 404:
+        return "absent", None
+    if resp.status_code != 200:
+        return "error", None
+    try:
+        doc = resp.json()
+    except Exception:
+        return "error", None
+    if not isinstance(doc, dict):
+        return "error", None
+    if looks_absent(doc):
+        return "absent", None
+    try:
+        return "present", adapter(doc)
+    except Exception:
+        # A malformed record the adapter can't map is not a claim of absence.
+        return "error", None

sm_divergence/discovery/closure.py

@@ -0,0 +1,15 @@
+"""Discovery bind-back predicate for alias closure (see
+``sm_divergence.identity.AliasClosureResolver``).
+"""
+
+from __future__ import annotations
+
+from .views import RecordView
+
+
+def binds_by_did(view: RecordView, expected_did: str) -> bool:
+    """Discovery bind-back: the record's VERIFIED did must equal the expected
+    ``did:key``. A record with no verified did (no valid attestation) cannot bind
+    back, so it contributes no claim — you cannot safely follow a claimed
+    discovery alias without a record that proves it is the same agent."""
+    return view.did is not None and view.did == expected_did

sm_divergence/discovery/http_by_id.py

@@ -0,0 +1,54 @@
+"""HttpByIdResolver — the ``GET {base}/api/agents/{id}`` registry shape (e.g. NEST).
+
+The reference discovery resolver: a thin adapter mapping a single-hop by-id HTTP
+registry onto the core ``Resolver`` protocol.
+"""
+
+from __future__ import annotations
+
+import httpx
+from sm_resolver import Status
+
+from .client import DEFAULT_PATH, RecordAdapter, default_adapter, fetch_view
+from .views import RecordView
+
+
+class HttpByIdResolver:
+    """A registry that serves ``GET {base}/api/agents/{id}``.
+
+    The record path and the record→view mapping are injectable, so this also
+    covers any single-hop by-id HTTP registry. ``transport`` is an injectable
+    httpx transport for tests; ``None`` uses the real network.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        adapter: RecordAdapter = default_adapter,
+        path: str = DEFAULT_PATH,
+        timeout: float = 10.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+        label: str | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.adapter = adapter
+        self.path = path
+        self.timeout = timeout
+        self._transport = transport
+        self._label = label or self.base_url
+
+    @property
+    def label(self) -> str:
+        return self._label
+
+    async def resolve(self, agent_id: str) -> tuple[Status, RecordView | None]:
+        async with httpx.AsyncClient(transport=self._transport) as client:
+            return await fetch_view(
+                client,
+                self.base_url,
+                agent_id,
+                adapter=self.adapter,
+                path=self.path,
+                timeout=self.timeout,
+            )