hypermind 0.11.0__py3-none-any.whl

hypermind/namespace.py

@@ -0,0 +1,515 @@
+"""Namespace lifecycle façade for HyperMind §24.
+
+Implements the four wire records of the namespace lifecycle:
+
+* ``NAMESPACE_CREATE`` — FROST-quorum-signed mint
+* ``NAMESPACE_FOUNDING_ATTEST`` — public attestation of the cohort
+* ``NAMESPACE_INVITE`` — single-member-signed admission grant
+* ``NAMESPACE_ACCEPT`` — invitee counter-signature
+
+This module is a thin façade over :class:`hypermind.agent._NamespaceWorld`:
+it constructs the records, anchors them in the world's transparency
+log, and tracks roster admission. Production deployments swap the
+in-process bus + TS for libp2p + a real SCITT TS — the public verbs do
+not change.
+
+Wire-record stub: at v0.9.x boundary another agent is bumping
+``wire.py`` to v2 with the new record-type literals. We import them
+defensively — if they are not yet declared we fall back to plain
+strings. The merge step at the end of Phase 5 reconciles both.
+"""
+
+from __future__ import annotations
+
+import secrets
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+import cbor2
+
+from hypermind.crypto.hashing import blake3_32
+from hypermind.crypto.hlc import HLC
+from hypermind.crypto.namespace_root import NamespaceRoot
+from hypermind.crypto.signing import Keypair
+from hypermind.did_web import DidDocument, format_did
+from hypermind.errors import AuthError, BlockReason, HyperMindError
+
+# The Literal alias does not expose constants; we still need stable strings.
+NAMESPACE_CREATE = "NAMESPACE_CREATE"
+NAMESPACE_FOUNDING_ATTEST = "NAMESPACE_FOUNDING_ATTEST"
+NAMESPACE_INVITE = "NAMESPACE_INVITE"
+NAMESPACE_ACCEPT = "NAMESPACE_ACCEPT"
+
+
+Visibility = Literal["public", "private", "hybrid"]
+_VISIBILITY_VALUES: tuple[str, ...] = ("public", "private", "hybrid")
+
+# Spec §24.4 default — invite validity ≤ 30 days.
+INVITE_MAX_VALIDITY_MS = 30 * 24 * 3600 * 1000
+
+
+def _new_namespace_id() -> bytes:
+    """16-byte UUIDv7-shaped namespace id (matches wire.new_namespace_id)."""
+    try:
+        from hypermind.wire import new_namespace_id
+
+        return new_namespace_id()
+    except ImportError:  # pragma: no cover
+        return secrets.token_bytes(16)
+
+
+@dataclass(frozen=True)
+class NamespaceMember:
+    """Founding-cohort member record (§24.3 ``member_list[]`` entry)."""
+
+    kid: bytes
+    jurisdiction: str = "XX"  # ISO 3166-1 alpha-2 or "XX" for undisclosed
+    org_did: str = ""
+    coi_disclosure_hash: bytes = b"\x00" * 32
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "kid": self.kid,
+            "jurisdiction": self.jurisdiction,
+            "org_did": self.org_did,
+            "coi_disclosure_hash": self.coi_disclosure_hash,
+        }
+
+
+@dataclass(frozen=True)
+class NamespaceInvite:
+    """A `NAMESPACE_INVITE` record (in-memory representation)."""
+
+    namespace_id: bytes
+    inviter_kid: bytes
+    invitee_kid: bytes
+    scope: dict[str, Any]
+    not_before_hlc: HLC
+    not_after_hlc: HLC
+    invite_id: bytes
+    signature: bytes
+
+    def canonical_payload(self) -> bytes:
+        return cbor2.dumps(
+            {
+                "ns_id": self.namespace_id,
+                "inviter_kid": self.inviter_kid,
+                "invitee_kid": self.invitee_kid,
+                "scope": self.scope,
+                "valid_from_hlc": self.not_before_hlc.to_cbor(),
+                "valid_until_hlc": self.not_after_hlc.to_cbor(),
+                "invite_id": self.invite_id,
+            },
+            canonical=True,
+        )
+
+    def hash(self) -> bytes:
+        return blake3_32(self.canonical_payload())
+
+
+@dataclass(frozen=True)
+class NamespaceAccept:
+    """A `NAMESPACE_ACCEPT` record (in-memory representation)."""
+
+    namespace_id: bytes
+    invitee_kid: bytes
+    invite_id: bytes
+    invite_hash: bytes
+    accepted_at_hlc: HLC
+    signature: bytes
+
+
+@dataclass
+class NamespacePolicy:
+    """Effective policy attached to a namespace.
+
+    v0.9.x carries only the cohort metadata + visibility. Future fields
+    (room admission rules, rate caps, COI thresholds) extend this dataclass
+    without breaking existing call sites.
+    """
+
+    visibility: Visibility = "private"
+    members: list[NamespaceMember] = field(default_factory=list)
+    jurisdictions: list[str] = field(default_factory=list)
+    coi_disclosure_hashes: list[bytes] = field(default_factory=list)
+
+
+class Namespace:
+    """Façade over :class:`hypermind.agent._NamespaceWorld` for §24 lifecycle.
+
+    Use :meth:`create` to mint a new namespace via FROST DKG. The
+    resulting ``Namespace`` exposes the policy, visibility, member
+    roster, current epoch, and DID:web URI.
+    """
+
+    def __init__(
+        self,
+        *,
+        namespace_id: bytes,
+        root: NamespaceRoot,
+        policy: NamespacePolicy,
+        host: str,
+        world: Any | None = None,
+        founding_keypairs: list[Keypair] | None = None,
+    ) -> None:
+        self._namespace_id = namespace_id
+        self._root = root
+        self._policy = policy
+        self._host = host
+        self._world = world  # _NamespaceWorld | None
+        self._roster: set[bytes] = {m.kid for m in policy.members}
+        # Map invite_id → (NamespaceInvite, NamespaceAccept | None)
+        self._invites: dict[bytes, tuple[NamespaceInvite, NamespaceAccept | None]] = {}
+        # Founding keypairs are needed to mint NAMESPACE_INVITE records;
+        # we keep a (private) reference indexed by kid.
+        self._keypairs: dict[bytes, Keypair] = {}
+        for kp in founding_keypairs or []:
+            self._keypairs[kp.kid] = kp
+
+    # ---- properties ---------------------------------------------------
+
+    @property
+    def namespace_id(self) -> bytes:
+        return self._namespace_id
+
+    @property
+    def policy(self) -> NamespacePolicy:
+        return self._policy
+
+    @property
+    def visibility(self) -> Visibility:
+        return self._policy.visibility
+
+    @property
+    def members(self) -> list[bytes]:
+        """Current roster — founding members plus admitted invitees."""
+        return list(self._roster)
+
+    @property
+    def epoch(self):
+        return self._root.epoch
+
+    @property
+    def root(self) -> NamespaceRoot:
+        return self._root
+
+    @property
+    def did(self) -> str:
+        return format_did(self._host, self._namespace_id)
+
+    # ---- factory ------------------------------------------------------
+
+    @classmethod
+    def create(
+        cls,
+        founding_keypairs: list[Keypair],
+        k: int = 5,
+        n: int = 7,
+        visibility: Visibility = "private",
+        *,
+        host: str = "localhost",
+        jurisdictions: list[str] | None = None,
+        coi_disclosure_hashes: list[bytes] | None = None,
+        org_dids: list[str] | None = None,
+        world: Any | None = None,
+    ) -> Namespace:
+        """Mint a new namespace via FROST DKG (spec §24.2 / §24.3).
+
+        Steps:
+            1. Run :meth:`NamespaceRoot.from_dkg` over the founders.
+            2. Build the ``NAMESPACE_FOUNDING_ATTEST`` payload.
+            3. Build the ``NAMESPACE_CREATE`` payload (FROST-signed).
+            4. Anchor both in the world's transparency log if a world
+               is supplied.
+            5. Register in the global namespace registry.
+        """
+        if visibility not in _VISIBILITY_VALUES:
+            raise ValueError(f"visibility must be one of {_VISIBILITY_VALUES}, got {visibility!r}")
+        if len(founding_keypairs) != n:
+            raise ValueError(f"founding_keypairs count {len(founding_keypairs)} != n={n}")
+        # Spec §24.2: k >= ceil(2n/3), n >= 3 — delegated to NamespaceRoot.from_dkg.
+        root = NamespaceRoot.from_dkg(founding_keypairs, k=k, n=n)
+
+        jurisdictions = jurisdictions or ["XX"] * n
+        coi_disclosure_hashes = coi_disclosure_hashes or [b"\x00" * 32] * n
+        org_dids = org_dids or [""] * n
+        if not (len(jurisdictions) == len(coi_disclosure_hashes) == len(org_dids) == n):
+            raise ValueError(
+                "jurisdictions / coi_disclosure_hashes / org_dids must each have length n"
+            )
+
+        members = [
+            NamespaceMember(
+                kid=kp.kid,
+                jurisdiction=jurisdictions[i],
+                org_did=org_dids[i],
+                coi_disclosure_hash=coi_disclosure_hashes[i],
+            )
+            for i, kp in enumerate(founding_keypairs)
+        ]
+        policy = NamespacePolicy(
+            visibility=visibility,
+            members=members,
+            jurisdictions=list(jurisdictions),
+            coi_disclosure_hashes=list(coi_disclosure_hashes),
+        )
+
+        ns_id = _new_namespace_id()
+        created_hlc = HLC.now(node_id=founding_keypairs[0].kid[:8])
+
+        # ---- NAMESPACE_FOUNDING_ATTEST payload ------------------------
+        attest_body = {
+            "ns_id": ns_id,
+            "members": [m.to_dict() for m in members],
+            "dkg_transcript_hash": root.dkg_transcript_hash,
+            "root_pubkey": root.group_pubkey,
+            "visibility": visibility,
+            "created_at_hlc": created_hlc.to_cbor(),
+            # Reserved (spec §24.3): MUST be present as null in v0.9.x.
+            "epoch_rotation_proof": None,
+            "mls_group_id": None,
+        }
+        attest_preimage = cbor2.dumps(attest_body, canonical=True)
+        attest_sig = root.sign(attest_preimage, signer_subset=list(range(1, k + 1)))
+        attest_record = {**attest_body, "frost_signature": attest_sig}
+
+        # ---- NAMESPACE_CREATE payload --------------------------------
+        create_body = {
+            "ns_id": ns_id,
+            "founding_cohort": [kp.kid for kp in founding_keypairs],
+            "threshold": {"k": k, "n": n},
+            "dkg_transcript_hash": root.dkg_transcript_hash,
+            "root_pubkey": root.group_pubkey,
+            "visibility": visibility,
+            "created_at_hlc": created_hlc.to_cbor(),
+        }
+        create_preimage = cbor2.dumps(create_body, canonical=True)
+        create_sig = root.sign(create_preimage, signer_subset=list(range(1, k + 1)))
+        create_record = {**create_body, "frost_signature": create_sig}
+
+        # ---- anchor in transparency log if world available -----------
+        if world is not None:
+            ts = getattr(world, "ts", None)
+            if ts is not None:
+                # Anchor the BLAKE3 hash of each canonical record as a leaf
+                # kid (§04 transparency uses 32-byte leaf identifiers).
+                attest_kid = blake3_32(cbor2.dumps(attest_record, canonical=True))
+                create_kid = blake3_32(cbor2.dumps(create_record, canonical=True))
+                try:
+                    ts.append_and_cosign(attest_kid)
+                    ts.append_and_cosign(create_kid)
+                except Exception:
+                    pass
+
+        ns = cls(
+            namespace_id=ns_id,
+            root=root,
+            policy=policy,
+            host=host,
+            world=world,
+            founding_keypairs=founding_keypairs,
+        )
+        # Stash the raw records for tests / audit (private attributes).
+        ns._founding_attest = attest_record
+        ns._namespace_create = create_record
+        return ns
+
+    # ---- invite / accept ---------------------------------------------
+
+    def invite(
+        self,
+        invitee_kid: bytes,
+        scope: dict[str, Any],
+        valid_window_hlc: tuple[HLC, HLC],
+        *,
+        inviter_kid: bytes | None = None,
+    ) -> NamespaceInvite:
+        """Issue a `NAMESPACE_INVITE` (§24.4).
+
+        Signed by an existing authorised member. ``inviter_kid``
+        defaults to the first founding member; in production an L5
+        admit-authority CapToken would gate this.
+        """
+        not_before, not_after = valid_window_hlc
+        if not_after.logical_ms < not_before.logical_ms:
+            raise ValueError("valid_window_hlc: not_after_hlc precedes not_before_hlc")
+        delta_ms = not_after.logical_ms - not_before.logical_ms
+        if delta_ms > INVITE_MAX_VALIDITY_MS:
+            raise ValueError(
+                f"invite validity window {delta_ms}ms exceeds spec max "
+                f"{INVITE_MAX_VALIDITY_MS}ms (§24.4)"
+            )
+        if inviter_kid is None:
+            inviter_kid = self._policy.members[0].kid
+        if inviter_kid not in self._roster:
+            raise AuthError(
+                "inviter is not a member of the namespace",
+                reason=BlockReason(
+                    rule_id="NS-INVITE-AUTH",
+                    spec_ref="§24.4",
+                    hint="Inviter kid must be in the current roster.",
+                ),
+            )
+        kp = self._keypairs.get(inviter_kid)
+        if kp is None:
+            raise AuthError(
+                "no keypair available to sign invite",
+                reason=BlockReason(
+                    rule_id="NS-INVITE-NO-KEY",
+                    spec_ref="§24.4",
+                    hint="Founding keypair was not registered with this Namespace facade.",
+                ),
+            )
+
+        invite_id = secrets.token_bytes(16)
+        unsigned = {
+            "ns_id": self._namespace_id,
+            "inviter_kid": inviter_kid,
+            "invitee_kid": invitee_kid,
+            "scope": scope,
+            "valid_from_hlc": not_before.to_cbor(),
+            "valid_until_hlc": not_after.to_cbor(),
+            "invite_id": invite_id,
+        }
+        signature = kp.sign(cbor2.dumps(unsigned, canonical=True))
+        invite = NamespaceInvite(
+            namespace_id=self._namespace_id,
+            inviter_kid=inviter_kid,
+            invitee_kid=invitee_kid,
+            scope=scope,
+            not_before_hlc=not_before,
+            not_after_hlc=not_after,
+            invite_id=invite_id,
+            signature=signature,
+        )
+        self._invites[invite_id] = (invite, None)
+        # Anchor the invite hash in TS (best-effort).
+        if self._world is not None:
+            ts = getattr(self._world, "ts", None)
+            if ts is not None:
+                try:
+                    ts.append_and_cosign(invite.hash())
+                except Exception:
+                    pass
+        return invite
+
+    def accept(self, invite: NamespaceInvite, invitee_kp: Keypair) -> NamespaceAccept:
+        """Counter-sign an invite (§24.5) and complete admission.
+
+        Spec §24.5: admission completes only when both records appear in
+        the transparency log. This implementation mirrors that — the
+        invitee is added to the roster only if the original invite is
+        registered with this Namespace and is within its validity window.
+        """
+        if invitee_kp.kid != invite.invitee_kid:
+            raise AuthError(
+                "accept signed by wrong kid",
+                reason=BlockReason(
+                    rule_id="NS-ACCEPT-WRONG-KID",
+                    spec_ref="§24.5",
+                    hint="The signing kid MUST equal NAMESPACE_INVITE.invitee_kid.",
+                ),
+            )
+        registered = self._invites.get(invite.invite_id)
+        if registered is None:
+            raise HyperMindError(
+                BlockReason(
+                    rule_id="NS-ACCEPT-NO-INVITE",
+                    spec_ref="§24.5",
+                    hint="No matching NAMESPACE_INVITE on file for this invite_id.",
+                )
+            )
+        # Check validity window against current HLC.
+        now = HLC.now(node_id=invitee_kp.kid[:8])
+        if now.logical_ms < invite.not_before_hlc.logical_ms:
+            raise HyperMindError(
+                BlockReason(
+                    rule_id="NS-ACCEPT-NOT-YET-VALID",
+                    spec_ref="§24.4",
+                    hint="Invite is not yet within its validity window.",
+                )
+            )
+        if now.logical_ms > invite.not_after_hlc.logical_ms:
+            raise HyperMindError(
+                BlockReason(
+                    rule_id="NS-ACCEPT-EXPIRED",
+                    spec_ref="§24.4",
+                    hint="Invite has expired (not_after_hlc passed).",
+                )
+            )
+
+        invite_hash = invite.hash()
+        unsigned = {
+            "ns_id": self._namespace_id,
+            "invitee_kid": invitee_kp.kid,
+            "invite_id": invite.invite_id,
+            "invite_hash": invite_hash,
+            "accepted_at_hlc": now.to_cbor(),
+        }
+        signature = invitee_kp.sign(cbor2.dumps(unsigned, canonical=True))
+        accept = NamespaceAccept(
+            namespace_id=self._namespace_id,
+            invitee_kid=invitee_kp.kid,
+            invite_id=invite.invite_id,
+            invite_hash=invite_hash,
+            accepted_at_hlc=now,
+            signature=signature,
+        )
+        # Admission completes — both records present.
+        self._invites[invite.invite_id] = (invite, accept)
+        self._roster.add(invitee_kp.kid)
+
+        if self._world is not None:
+            ts = getattr(self._world, "ts", None)
+            if ts is not None:
+                try:
+                    ts.append_and_cosign(blake3_32(cbor2.dumps(unsigned, canonical=True)))
+                except Exception:
+                    pass
+        return accept
+
+    # ---- visibility / payload gating ---------------------------------
+
+    def require_l3_envelope(self) -> bool:
+        """True iff payload records MUST be L3-encrypted (§24.7)."""
+        return self._policy.visibility in ("private", "hybrid")
+
+    def gate_plaintext_payload(self, statement: Any) -> None:
+        """Raise if plaintext payload arrives in a non-public namespace.
+
+        Future work: when L5 separability lands, this gate should run on
+        the SignedStatement ingest path so receivers automatically emit
+        ``BlockReason("CASCADE-L3-PLAINTEXT-IN-PRIVATE-NS")`` (spec §24.7).
+        """
+        if self.require_l3_envelope():
+            raise HyperMindError(
+                BlockReason(
+                    rule_id="CASCADE-L3-PLAINTEXT-IN-PRIVATE-NS",
+                    spec_ref="§24.7",
+                    hint=(
+                        f"namespace visibility={self._policy.visibility} requires "
+                        "L3-encrypted payloads; received plaintext SignedStatement."
+                    ),
+                )
+            )
+
+    def build_did_document(self, gossip_endpoints: list[str]) -> DidDocument:
+        """Build the DID:web rendezvous document (§24.6)."""
+        return DidDocument.build(
+            ns=self._root,
+            host=self._host,
+            gossip_endpoints=gossip_endpoints,
+            ns_id=self._namespace_id,
+        )
+
+    # ---- introspection -----------------------------------------------
+
+    @property
+    def founding_attest(self) -> dict[str, Any]:
+        """The signed `NAMESPACE_FOUNDING_ATTEST` record (read-only view)."""
+        return dict(self._founding_attest)
+
+    @property
+    def namespace_create(self) -> dict[str, Any]:
+        """The signed `NAMESPACE_CREATE` record (read-only view)."""
+        return dict(self._namespace_create)