hypermind 0.11.0__py3-none-any.whl

hypermind/namespace_policy.py

@@ -0,0 +1,254 @@
+"""Namespace-level policy primitives.
+
+Each namespace has a single root-signed ``NamespacePolicy`` that
+declares the federation rules every member MUST honour. v0.7 adds
+``min_signature_alg`` — the explicit pin that lets a namespace REFUSE
+classical-only Ed25519 statements once the federation is ready to be
+"PQ-only".
+
+Existing pq-related controls:
+
+* ``pq_required`` (per-statement, in the protected header) is the
+  per-message gate that says "this statement was signed with a PQ-hybrid
+  key". Verifiers MAY require it on individual records.
+* ``min_signature_alg`` (this module) is the per-namespace floor; a
+  statement whose ``alg`` does not meet the floor is rejected with
+  ``rule_id="HM-MIN-ALG-001"`` regardless of its ``pq_required`` flag.
+
+Forward-compatibility: future PQ-only algorithms (e.g. SLH-DSA-only
+profiles) extend ``MIN_ALG_ORDERING`` without breaking existing pins.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from hypermind.crypto.signing import ALG_ED25519, ALG_MLDSA65_ED25519
+from hypermind.errors import BlockReason
+from hypermind.rule_ids import MIN_ALG, SPEC_REFS
+
+#: Allowed `by` kinds for ACL entries (spec §25.4).
+ACLPrincipalKind = Literal["agent_id", "org_did", "room_id", "topic_glob"]
+_VALID_ACL_PRINCIPAL_KINDS: frozenset[str] = frozenset(
+    {
+        "agent_id",
+        "org_did",
+        "room_id",
+        "topic_glob",
+    }
+)
+
+#: String ids the policy uses (rather than COSE ints) so the policy is
+#: human-readable when serialized to YAML / JSON.
+ALG_NAME_ED25519 = "ed25519"
+ALG_NAME_COMPOSITE = "composite-mldsa65-ed25519"
+
+#: Map between policy-string ids and COSE-int ids.
+ALG_NAME_TO_COSE: dict[str, int] = {
+    ALG_NAME_ED25519: ALG_ED25519,
+    ALG_NAME_COMPOSITE: ALG_MLDSA65_ED25519,
+}
+COSE_TO_ALG_NAME: dict[int, str] = {v: k for k, v in ALG_NAME_TO_COSE.items()}
+
+#: Total ordering of supported sig algs from weakest to strongest. Larger
+#: index ⇒ stricter (composite ≥ ed25519). New PQ-only algs are appended.
+MIN_ALG_ORDERING: tuple[str, ...] = (ALG_NAME_ED25519, ALG_NAME_COMPOSITE)
+
+
+def _alg_rank(name: str) -> int:
+    try:
+        return MIN_ALG_ORDERING.index(name)
+    except ValueError as e:
+        raise ValueError(
+            f"unknown signature alg id {name!r}; supported: {MIN_ALG_ORDERING!r}"
+        ) from e
+
+
+@dataclass(frozen=True, slots=True)
+class ACLEntry:
+    """A single allow/deny ACL entry (spec §25.4).
+
+    ``by`` selects the principal-kind matcher: ``agent_id`` (lowercase
+    hex kid), ``org_did`` (string DID), ``room_id`` (lowercase hex), or
+    ``topic_glob`` (path-style glob with ``*`` and ``**``; spec §25.4
+    grammar).
+    """
+
+    by: ACLPrincipalKind
+    value: str
+
+    def __post_init__(self) -> None:
+        if self.by not in _VALID_ACL_PRINCIPAL_KINDS:
+            raise ValueError(
+                f"ACLEntry.by must be one of {sorted(_VALID_ACL_PRINCIPAL_KINDS)!r}; "
+                f"got {self.by!r}"
+            )
+        if not isinstance(self.value, str):
+            raise ValueError("ACLEntry.value must be a string")
+
+
+def _glob_match(glob: str, path: str) -> bool:
+    """Spec §25.4 path-style glob: only ``*`` (single segment) and ``**``
+    (zero or more segments) are permitted. Case-sensitive. Empty glob
+    matches nothing; ``**`` matches everything.
+    """
+    if glob == "":
+        return False
+    if glob == "**":
+        return True
+    g_parts = glob.split("/")
+    p_parts = path.split("/")
+    return _glob_match_parts(g_parts, p_parts)
+
+
+def _glob_match_parts(g: list[str], p: list[str]) -> bool:
+    # Recursive descent. Forbid backslash escapes and any metachar other
+    # than * / **.
+    if not g:
+        return not p
+    head = g[0]
+    if head == "**":
+        # Match zero or more segments.
+        if len(g) == 1:
+            return True
+        for i in range(0, len(p) + 1):
+            if _glob_match_parts(g[1:], p[i:]):
+                return True
+        return False
+    if not p:
+        return False
+    if head == "*":
+        return _glob_match_parts(g[1:], p[1:])
+    # Literal segment — backslash escapes are forbidden; any other use
+    # of `*` inside a segment (e.g. `foo*`) is also forbidden by §25.4.
+    if "\\" in head or "*" in head:
+        return False
+    if head != p[0]:
+        return False
+    return _glob_match_parts(g[1:], p[1:])
+
+
+@dataclass(frozen=True, slots=True)
+class NamespacePolicy:
+    """Root-signed policy for a namespace.
+
+    For v0.7, only the ``min_signature_alg`` field is normative. The
+    other fields stub out the surface that ROADMAP §0.7 will populate
+    (panel-quorum sizes, ramp lengths, witness cohort, etc.); they
+    default to None so existing tests don't need to set them.
+    """
+
+    namespace_id: bytes
+    #: One of `MIN_ALG_ORDERING`. Statements whose alg is below this
+    #: floor are rejected with rule_id `HM-MIN-ALG-001`.
+    min_signature_alg: str = ALG_NAME_ED25519
+    #: Per-namespace pq_required flag — when True, every statement must
+    #: also carry `pq_required=True` in its protected header. (Already
+    #: partially supported via the wire-level pq_required bit; pinning
+    #: the alg floor here gives operators an upgrade path.)
+    pq_required: bool = False
+    #: Optional human-readable name (debug/UX only).
+    label: str | None = None
+    #: ACL allow-entries (spec §25.4). Empty tuple = no explicit allow rules
+    #: (closed-by-default still applies).
+    allow: tuple[ACLEntry, ...] = ()
+    #: ACL deny-entries (spec §25.4). Deny precedence applies.
+    deny: tuple[ACLEntry, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.namespace_id, (bytes, bytearray)) or len(self.namespace_id) != 16:
+            raise ValueError("NamespacePolicy.namespace_id must be 16 bytes")
+        if self.min_signature_alg not in MIN_ALG_ORDERING:
+            raise ValueError(
+                f"min_signature_alg must be one of {MIN_ALG_ORDERING!r}; "
+                f"got {self.min_signature_alg!r}"
+            )
+        # Coerce list ⇒ tuple so frozen dataclass equality works.
+        if isinstance(self.allow, list):
+            object.__setattr__(self, "allow", tuple(self.allow))
+        if isinstance(self.deny, list):
+            object.__setattr__(self, "deny", tuple(self.deny))
+        for e in (*self.allow, *self.deny):
+            if not isinstance(e, ACLEntry):
+                raise ValueError("NamespacePolicy.allow/deny entries must be ACLEntry instances")
+
+    # -- ACL evaluation (spec §25.4) ---------------------------------- #
+
+    def evaluate(self, action_ctx: dict[str, Any]) -> Literal["allow", "deny"]:
+        """Evaluate ACL against an action context (spec §25.4).
+
+        ``action_ctx`` is a dict that may contain any of:
+
+        - ``agent_id``: lowercase hex of the operating kid.
+        - ``org_did``: org_did string for the operating kid.
+        - ``room_id``: lowercase hex of the operation's Room.
+        - ``topic``: topic identifier (matched against ``topic_glob`` rules).
+
+        Returns ``"deny"`` whenever a deny rule matches (deny precedence),
+        ``"allow"`` if an allow rule matches and no deny matched, and
+        ``"deny"`` by default if neither matched (closed-by-default).
+        """
+        # Deny precedence: evaluate deny first.
+        for entry in self.deny:
+            if self._matches(entry, action_ctx):
+                return "deny"
+        for entry in self.allow:
+            if self._matches(entry, action_ctx):
+                return "allow"
+        return "deny"
+
+    @staticmethod
+    def _matches(entry: ACLEntry, ctx: dict[str, Any]) -> bool:
+        if entry.by == "agent_id":
+            v = ctx.get("agent_id")
+            return isinstance(v, str) and v.lower() == entry.value.lower()
+        if entry.by == "org_did":
+            v = ctx.get("org_did")
+            return isinstance(v, str) and v == entry.value
+        if entry.by == "room_id":
+            v = ctx.get("room_id")
+            return isinstance(v, str) and v.lower() == entry.value.lower()
+        if entry.by == "topic_glob":
+            v = ctx.get("topic")
+            if not isinstance(v, str):
+                return False
+            return _glob_match(entry.value, v)
+        return False
+
+    # -- gating ------------------------------------------------------- #
+
+    def alg_meets_floor(self, alg_cose: int) -> bool:
+        """True iff the COSE alg id meets `min_signature_alg`."""
+        name = COSE_TO_ALG_NAME.get(alg_cose)
+        if name is None:
+            # Unknown alg cannot meet a known floor.
+            return False
+        return _alg_rank(name) >= _alg_rank(self.min_signature_alg)
+
+    def block_reason_for_alg(self, alg_cose: int) -> BlockReason:
+        """Build the canonical BlockReason for a sub-floor signature."""
+        observed = COSE_TO_ALG_NAME.get(alg_cose, f"alg={alg_cose}")
+        return BlockReason(
+            rule_id=MIN_ALG,
+            spec_ref=SPEC_REFS[MIN_ALG],
+            hint=(
+                f"namespace pins min_signature_alg={self.min_signature_alg!r} "
+                f"but the statement is signed with {observed!r}; "
+                "rotate the issuer to a key that meets the floor."
+            ),
+            current_value=observed,
+            required_value=self.min_signature_alg,
+        )
+
+
+__all__ = [
+    "ALG_NAME_COMPOSITE",
+    "ALG_NAME_ED25519",
+    "ALG_NAME_TO_COSE",
+    "COSE_TO_ALG_NAME",
+    "MIN_ALG_ORDERING",
+    "ACLEntry",
+    "ACLPrincipalKind",
+    "NamespacePolicy",
+]

hypermind/observability/__init__.py

@@ -0,0 +1,25 @@
+"""Observability primitives.
+
+The SDK emits structured logs in the shape mandated by spec/13-observability.md.
+OpenTelemetry tracing and Prometheus metrics are optional; the
+in-process recorder always works for tests.
+"""
+
+from hypermind.observability.cost import (
+    PRICE_TABLE,
+    PRICE_TABLE_VERSION,
+    TokenCostTracker,
+    cost_usd,
+)
+from hypermind.observability.otel_export import OtelExporter
+from hypermind.observability.recorder import Recorder, get_recorder
+
+__all__ = [
+    "PRICE_TABLE",
+    "PRICE_TABLE_VERSION",
+    "OtelExporter",
+    "Recorder",
+    "TokenCostTracker",
+    "cost_usd",
+    "get_recorder",
+]

hypermind/observability/asgi.py

@@ -0,0 +1,214 @@
+"""Minimal ASGI 3 app exposing `/healthz` and `/metrics`.
+
+Designed to be zero-dependency: the SDK already exposes the bounded
+`Recorder` and the `wire_version` / `protocol_version` constants, so
+production operators can mount this app under any ASGI server
+(uvicorn, hypercorn, daphne) and get health + Prometheus metrics
+without pulling in `prometheus-client`.
+
+Usage::
+
+    from hypermind.observability.asgi import asgi_app
+
+    app = asgi_app()                 # uses the global Recorder
+    # uvicorn.run(app, host="0.0.0.0", port=9100)
+
+    # Or with a scoped Recorder:
+    rec = Recorder.scoped("did:web:my-namespace")
+    app = asgi_app(recorder=rec)
+
+The exposition format follows the Prometheus text 0.0.4 spec
+(https://prometheus.io/docs/instrumenting/exposition_formats/) — one
+line per labelled counter, plus `# HELP` / `# TYPE` headers.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from hypermind.observability.recorder import Recorder, get_recorder
+
+# ASGI-3 callable type
+_Send = Callable[[dict[str, Any]], Awaitable[None]]
+_Receive = Callable[[], Awaitable[dict[str, Any]]]
+_Scope = dict[str, Any]
+
+
+# Prometheus metric names: [a-zA-Z_:][a-zA-Z0-9_:]*
+_METRIC_NAME_RE = re.compile(r"^[a-zA-Z_:][a-zA-Z0-9_:]*$")
+_LABEL_RE = re.compile(r"^([^{}=,]+)\{(.*)\}$")
+
+
+def _parse_metric_key(key: str) -> tuple[str, dict[str, str]]:
+    """Split ``"name{label=value,...}"`` → ``("name", {"label": "value"})``."""
+    m = _LABEL_RE.match(key)
+    if not m:
+        return key, {}
+    name = m.group(1)
+    body = m.group(2)
+    labels: dict[str, str] = {}
+    for part in body.split(","):
+        if "=" not in part:
+            continue
+        k, v = part.split("=", 1)
+        labels[k.strip()] = v.strip()
+    return name, labels
+
+
+def _escape_label_value(v: str) -> str:
+    return v.replace("\\", "\\\\").replace("\n", "\\n").replace('"', '\\"')
+
+
+def _render_prometheus(recorder: Recorder) -> bytes:
+    """Render the Recorder's counters in Prometheus text 0.0.4 format."""
+    snapshot = recorder.get_metrics()
+    counters: dict[str, float] = snapshot["counters"]
+
+    # Group by metric name so we can emit one HELP/TYPE per family.
+    grouped: dict[str, list[tuple[dict[str, str], float]]] = {}
+    for key, value in counters.items():
+        name, labels = _parse_metric_key(key)
+        if not _METRIC_NAME_RE.match(name):
+            # Skip names that would corrupt the exposition format.
+            continue
+        grouped.setdefault(name, []).append((labels, value))
+
+    lines: list[str] = []
+    for name in sorted(grouped):
+        lines.append(f"# HELP {name} HyperMind counter (auto-generated)")
+        lines.append(f"# TYPE {name} counter")
+        for labels, value in grouped[name]:
+            if labels:
+                label_str = ",".join(
+                    f'{k}="{_escape_label_value(v)}"' for k, v in sorted(labels.items())
+                )
+                lines.append(f"{name}{{{label_str}}} {value}")
+            else:
+                lines.append(f"{name} {value}")
+
+    # Recorder-internal gauges — useful for ops to detect log-buffer
+    # saturation in long-running processes.
+    lines.append("# HELP hypermind_records_total Records currently in the bounded ring buffer")
+    lines.append("# TYPE hypermind_records_total gauge")
+    lines.append(f"hypermind_records_total {snapshot['records_total']}")
+    lines.append(
+        "# HELP hypermind_records_dropped_total Records dropped from the bounded ring buffer"
+    )
+    lines.append("# TYPE hypermind_records_dropped_total counter")
+    lines.append(f"hypermind_records_dropped_total {snapshot['records_dropped_total']}")
+
+    body = "\n".join(lines) + "\n"
+    return body.encode("utf-8")
+
+
+def _healthz_body() -> bytes:
+    # Late import — avoids a hard cycle if wire.py imports observability.
+    from hypermind.wire import PROTOCOL_VERSION, WIRE_VERSION
+
+    payload = {
+        "status": "ok",
+        "wire_version": WIRE_VERSION,
+        "protocol_version": PROTOCOL_VERSION,
+    }
+    return json.dumps(payload).encode("utf-8")
+
+
+async def _send_response(
+    send: _Send,
+    *,
+    status: int,
+    body: bytes,
+    content_type: str,
+) -> None:
+    await send(
+        {
+            "type": "http.response.start",
+            "status": status,
+            "headers": [
+                (b"content-type", content_type.encode("ascii")),
+                (b"content-length", str(len(body)).encode("ascii")),
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": body, "more_body": False})
+
+
+def asgi_app(
+    recorder: Recorder | None = None,
+) -> Callable[[_Scope, _Receive, _Send], Awaitable[None]]:
+    """Return an ASGI 3 application exposing `/healthz` and `/metrics`.
+
+    Both endpoints accept GET and HEAD; everything else gets 405.
+    Unknown paths get 404.
+    """
+
+    rec = recorder if recorder is not None else get_recorder()
+
+    async def app(scope: _Scope, receive: _Receive, send: _Send) -> None:
+        if scope["type"] == "lifespan":
+            # Drain the lifespan loop so uvicorn's startup completes.
+            while True:
+                message = await receive()
+                if message["type"] == "lifespan.startup":
+                    await send({"type": "lifespan.startup.complete"})
+                elif message["type"] == "lifespan.shutdown":
+                    await send({"type": "lifespan.shutdown.complete"})
+                    return
+            # unreachable — `return` above ends the lifespan task
+
+        if scope["type"] != "http":
+            return
+
+        method: str = scope.get("method", "GET").upper()
+        path: str = scope.get("path", "/")
+
+        if path == "/healthz":
+            if method not in ("GET", "HEAD"):
+                await _send_response(
+                    send,
+                    status=405,
+                    body=b"method not allowed",
+                    content_type="text/plain; charset=utf-8",
+                )
+                return
+            body = _healthz_body() if method == "GET" else b""
+            await _send_response(
+                send,
+                status=200,
+                body=body,
+                content_type="application/json",
+            )
+            return
+
+        if path == "/metrics":
+            if method not in ("GET", "HEAD"):
+                await _send_response(
+                    send,
+                    status=405,
+                    body=b"method not allowed",
+                    content_type="text/plain; charset=utf-8",
+                )
+                return
+            body = _render_prometheus(rec) if method == "GET" else b""
+            await _send_response(
+                send,
+                status=200,
+                body=body,
+                content_type="text/plain; version=0.0.4; charset=utf-8",
+            )
+            return
+
+        await _send_response(
+            send,
+            status=404,
+            body=b"not found",
+            content_type="text/plain; charset=utf-8",
+        )
+
+    return app
+
+
+__all__ = ["asgi_app"]