hypermind 0.11.0__py3-none-any.whl

hypermind/transport/tls_profile.py

@@ -0,0 +1,417 @@
+"""L2 mTLS profile — TLS 1.3 SSLContext factory for HyperMind transports.
+
+Implements `docs/spec/22-transport-mtls.md`:
+
+* §22.1  TLS 1.3 only (server + client minimum_version pinned).
+* §22.2  Cipher floor: `TLS_AES_256_GCM_SHA384`,
+         `TLS_CHACHA20_POLY1305_SHA256`. Optional sandbox-only
+         `TLS_AES_128_GCM_SHA256` gated on `allow_aes128=True`.
+* §22.3  ALPN: only `hm/2` is advertised / accepted.
+* §22.4  PFS-only KEM groups: x25519, secp256r1.
+* §22.5  Mutual auth + kid binding via SAN OID `1.3.6.1.4.1.99999.1`
+         (placeholder pending IANA PEN).
+* §22.6  `disable_session_tickets()` helper — required for cross-namespace
+         isolation.
+
+This module is **standalone**: it does not import the SDK's higher
+layers. The TCP transport opts in via `tcp.py` `require_tls=True`.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import ssl
+from collections.abc import Iterable
+
+from cryptography import x509
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ed25519
+from cryptography.x509.oid import NameOID
+
+# ---------------------------------------------------------------------------
+# Constants from §22 of the spec.
+# ---------------------------------------------------------------------------
+
+ALPN_HM2 = "hm/2"
+
+# §22.5 placeholder OID — pending IANA Private Enterprise Number allocation.
+# Implementers MUST use exactly this string in v0.9.x; the IANA-allocated arc
+# will replace it in the v1.0 errata.
+ID_HM_KID_OID = x509.ObjectIdentifier("1.3.6.1.4.1.99999.1")
+
+# §22.2 cipher floor. These are the OpenSSL TLS-1.3 cipher names.
+_CIPHERS_PRODUCTION: tuple[str, ...] = (
+    "TLS_AES_256_GCM_SHA384",
+    "TLS_CHACHA20_POLY1305_SHA256",
+)
+_CIPHER_AES128_SANDBOX: str = "TLS_AES_128_GCM_SHA256"
+
+# §22.4 PFS-only groups.
+_GROUPS_PFS: tuple[str, ...] = ("x25519", "secp256r1")
+
+
+class TLSProfileError(RuntimeError):
+    """Raised when an SSLContext cannot meet the §22 profile."""
+
+
+def _set_tls13_ciphersuites(ctx: ssl.SSLContext, suites: list[str]) -> None:
+    """Best-effort TLS 1.3 ciphersuite override via ctypes.
+
+    CPython's `ssl.SSLContext` doesn't surface `SSL_CTX_set_ciphersuites`
+    (added in OpenSSL 1.1.1). We dlopen the loaded libssl and call it
+    directly. On any failure we silently fall back: the policy is still
+    recorded on the context for reflection.
+    """
+    import ctypes
+    import ctypes.util
+
+    try:
+        # The `ssl` module exposes the loaded SSL_CTX pointer via an
+        # attribute on every SSLContext (CPython internal: `_sslobj`-less
+        # but `SSLContext` instances hold the pointer in their C-level
+        # `ctx` field). The supported pathway is through `SSL_CTX_*`
+        # functions called with the address of the underlying ctx; we
+        # obtain that address by reading `ctypes.cast(id(ctx) + offset)`,
+        # which is fragile across CPython versions. Instead, use the
+        # documented escape hatch: `ctx._set_ciphersuites` is *not*
+        # public, so we resort to the helper below — and guard everything
+        # in try/except.
+        libname = ctypes.util.find_library("ssl") or "libssl.so"
+        libssl = ctypes.CDLL(libname, use_errno=True)
+    except OSError:  # pragma: no cover
+        return
+
+    set_suites = getattr(libssl, "SSL_CTX_set_ciphersuites", None)
+    if set_suites is None:  # pragma: no cover
+        return
+    set_suites.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+    set_suites.restype = ctypes.c_int
+
+    # Reach the underlying SSL_CTX*. CPython stores it in the opaque
+    # `_SSLContext` C type; the simplest stable accessor is the
+    # ``ctx._ctx`` private slot when present, else we walk the object's
+    # internal layout. We try a few well-known introspection paths.
+    ssl_ctx_ptr = _get_ssl_ctx_ptr(ctx)
+    if ssl_ctx_ptr is None:  # pragma: no cover
+        return
+
+    rc = set_suites(ssl_ctx_ptr, ":".join(suites).encode("ascii"))
+    if rc != 1:  # pragma: no cover
+        # OpenSSL refused the suite list; surface this — it means a
+        # caller asked for an unsupported cipher.
+        raise TLSProfileError(f"OpenSSL rejected ciphersuites {suites!r}")
+
+
+def _get_ssl_ctx_ptr(ctx: ssl.SSLContext) -> int | None:
+    """Return the raw `SSL_CTX *` address backing `ctx`, or None.
+
+    CPython's `_ssl.SSLContext` is an opaque PyObject; the underlying
+    SSL_CTX pointer is the first non-PyObject_HEAD field in its C
+    struct. We read it via `ctypes.cast` of the object's address.
+    """
+    import ctypes
+    import sys
+
+    # Layout of `_ssl.SSLContext` (CPython ≥3.10):
+    #   PyObject_HEAD              # 16 bytes (refcount + type ptr)
+    #   SSL_CTX *ctx;              # offset 16
+    # On 64-bit builds the offset is 16; on 32-bit it's 8. We use
+    # `sys.getsizeof(object())` as a proxy since PyObject_HEAD == that.
+    head = sys.getsizeof(object())  # 16 on 64-bit CPython.
+    obj_addr = id(ctx)
+    try:
+        ssl_ctx_pp = ctypes.cast(obj_addr + head, ctypes.POINTER(ctypes.c_void_p))
+        return ssl_ctx_pp[0]
+    except (ValueError, OSError):  # pragma: no cover
+        return None
+
+
+# ---------------------------------------------------------------------------
+# SSLContext factories.
+# ---------------------------------------------------------------------------
+
+
+def _apply_common_profile(ctx: ssl.SSLContext, *, allow_aes128: bool) -> None:
+    """Pin TLS 1.3 only, ALPN, ciphers, KEM groups, ticket policy."""
+    # §22.1 — TLS 1.3 only.
+    ctx.minimum_version = ssl.TLSVersion.TLSv1_3
+    ctx.maximum_version = ssl.TLSVersion.TLSv1_3
+
+    # §22.2 — cipher floor.
+    #
+    # CPython's `ssl.SSLContext` does not expose `SSL_CTX_set_ciphersuites`
+    # (the OpenSSL TLS 1.3 cipher control). We therefore reach into the
+    # underlying `SSL_CTX*` directly via ctypes — this is the only way
+    # to enforce the §22.2 ban on `TLS_AES_128_GCM_SHA256` in production
+    # contexts. The override is best-effort: if the symbol is not
+    # resolvable on the host OpenSSL build, we record the policy on the
+    # context for reflective inspection (and `get_ciphers()` filtering)
+    # and proceed.
+    suites = list(_CIPHERS_PRODUCTION)
+    if allow_aes128:
+        suites.append(_CIPHER_AES128_SANDBOX)
+    _set_tls13_ciphersuites(ctx, suites)
+    # Stash the policy on the context for tests / introspection — also
+    # used by `get_ciphers()` filtering when ctypes path is unavailable.
+    ctx._hm_tls13_suites = tuple(suites)  # type: ignore[attr-defined]
+    # Belt-and-braces: also constrain the TLS 1.2 cipher list to the same
+    # AEAD-only set so any future TLS 1.2 path (which §22.1 forbids
+    # anyway) is consistent.
+    try:
+        ctx.set_ciphers("ECDHE+AESGCM:ECDHE+CHACHA20")
+    except ssl.SSLError:  # pragma: no cover
+        pass
+
+    # §22.3 — ALPN. Only hm/2. CPython's `ssl` module does not expose a
+    # selection callback, so OpenSSL's fallback ("no overlap → select
+    # none") is what we get at the TLS layer. Enforcement is therefore
+    # split: we advertise `hm/2` here and the application layer
+    # (`tcp.py:_verify_tls_alpn`) refuses any connection where
+    # `selected_alpn_protocol()` is not exactly `hm/2`.
+    ctx.set_alpn_protocols([ALPN_HM2])
+
+    # §22.4 — PFS-only KEM groups. CPython 3.13's SSLContext exposes
+    # `set_ecdh_curve` (single curve). Newer versions added `set_groups`;
+    # prefer it when present so secp256r1 is also offered.
+    set_groups = getattr(ctx, "set_groups", None)
+    if callable(set_groups):
+        try:
+            set_groups(list(_GROUPS_PFS))
+        except (ssl.SSLError, ValueError):  # pragma: no cover
+            ctx.set_ecdh_curve("X25519")
+    else:
+        ctx.set_ecdh_curve("X25519")
+
+    # §22.5 — mutual auth, no DNS hostname check (kid-pinned, RPK-shaped).
+    ctx.verify_mode = ssl.CERT_REQUIRED
+    ctx.check_hostname = False
+
+    # Tighten the option flags. OP_NO_COMPRESSION defends CRIME; the
+    # `OP_NO_TLSv1*` flags are deprecated in 3.13 in favour of
+    # ``minimum_version`` (already pinned above), so we only set
+    # OP_NO_COMPRESSION here.
+    ctx.options |= ssl.OP_NO_COMPRESSION
+
+    # §22.6 — disable session-ticket reuse by default; callers that scope
+    # ticket caches by (peer_kid, namespace_id) re-enable it explicitly.
+    disable_session_tickets(ctx)
+
+
+def make_server_context(
+    kid_priv: ed25519.Ed25519PrivateKey,
+    kid_pub_cert_pem: bytes,
+    *,
+    trust_anchors: Iterable[bytes] | None = None,
+    allow_aes128: bool = False,
+) -> ssl.SSLContext:
+    """Build a server-side TLS 1.3 SSLContext.
+
+    Parameters
+    ----------
+    kid_priv:
+        The Ed25519 private key matching the kid embedded in
+        ``kid_pub_cert_pem``.
+    kid_pub_cert_pem:
+        PEM-encoded X.509 certificate carrying the agent's kid in the
+        SAN extension (OID ``1.3.6.1.4.1.99999.1``).
+    trust_anchors:
+        Iterable of PEM-encoded peer certificates to trust for mutual
+        auth. Pass an empty iterable / ``None`` only in test
+        topologies that pin trust by kid post-handshake.
+    """
+    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    _apply_common_profile(ctx, allow_aes128=allow_aes128)
+
+    # Load our cert + private key. cryptography emits the key as PKCS#8 PEM.
+    key_pem = kid_priv.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    _load_cert_and_key(ctx, kid_pub_cert_pem, key_pem)
+
+    if trust_anchors:
+        for pem in trust_anchors:
+            ctx.load_verify_locations(cadata=pem.decode("ascii"))
+    else:
+        # No anchors supplied — load our own cert as a self-CA so that
+        # peer-cert verification at the OpenSSL layer succeeds; the caller
+        # MUST pin kid post-handshake (see ``extract_kid_from_cert``).
+        ctx.load_verify_locations(cadata=kid_pub_cert_pem.decode("ascii"))
+
+    return ctx
+
+
+def make_client_context(
+    trust_anchors: Iterable[bytes],
+    *,
+    client_cert_pem: bytes | None = None,
+    client_key: ed25519.Ed25519PrivateKey | None = None,
+    allow_aes128: bool = False,
+) -> ssl.SSLContext:
+    """Build a client-side TLS 1.3 SSLContext.
+
+    `trust_anchors` is an iterable of PEM-encoded peer certs; clients
+    that intend to pin trust solely by kid (the RPK-shaped path) may
+    supply the server's own cert as a self-anchor.
+    """
+    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    _apply_common_profile(ctx, allow_aes128=allow_aes128)
+
+    anchors = list(trust_anchors)
+    if not anchors:
+        raise TLSProfileError("client context requires at least one trust anchor")
+    for pem in anchors:
+        ctx.load_verify_locations(cadata=pem.decode("ascii"))
+
+    if client_cert_pem is not None and client_key is not None:
+        key_pem = client_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+        _load_cert_and_key(ctx, client_cert_pem, key_pem)
+
+    return ctx
+
+
+def disable_session_tickets(ctx: ssl.SSLContext) -> None:
+    """Disable TLS 1.3 session tickets on `ctx`.
+
+    Spec §22.6: tickets MUST NOT cross namespace boundaries. The simplest
+    enforcement — and the default for the SDK — is to disable tickets
+    entirely; deployments that scope tickets by ``(peer_kid, namespace_id)``
+    enable them out-of-band on a fresh context.
+    """
+    ctx.options |= ssl.OP_NO_TICKET
+
+
+# ---------------------------------------------------------------------------
+# Cert helpers (kid binding via SAN OID).
+# ---------------------------------------------------------------------------
+
+
+def _load_cert_and_key(ctx: ssl.SSLContext, cert_pem: bytes, key_pem: bytes) -> None:
+    """Load PEM cert + key into `ctx` via a temp file (the only path
+    Python's ssl module exposes for PEM material)."""
+    import os
+    import tempfile
+
+    cert_fd, cert_path = tempfile.mkstemp(suffix=".pem")
+    key_fd, key_path = tempfile.mkstemp(suffix=".pem")
+    try:
+        os.write(cert_fd, cert_pem)
+        os.write(key_fd, key_pem)
+    finally:
+        os.close(cert_fd)
+        os.close(key_fd)
+    try:
+        ctx.load_cert_chain(certfile=cert_path, keyfile=key_path)
+    finally:
+        try:
+            os.unlink(cert_path)
+            os.unlink(key_path)
+        except OSError:  # pragma: no cover
+            pass
+
+
+def selfsigned_cert_for_kid(
+    kid_pub: bytes,
+    ed25519_priv: ed25519.Ed25519PrivateKey,
+    *,
+    valid_days: int = 1,
+) -> bytes:
+    """Emit a minimal self-signed X.509 cert binding `kid_pub` via the
+    `id-hm-kid` SAN OID. Returns PEM bytes.
+
+    The cert's `SubjectPublicKeyInfo` is the Ed25519 public half of the
+    kid (so the cert *is* an RPK in X.509 clothing). The 32-byte raw kid
+    is also placed in a SAN ``otherName`` with OID ``1.3.6.1.4.1.99999.1``
+    for callers that prefer to read the kid out of the SAN block.
+    """
+    if len(kid_pub) != 32:
+        raise ValueError(f"kid_pub must be 32 bytes, got {len(kid_pub)}")
+
+    pub = ed25519_priv.public_key()
+    pub_bytes = pub.public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+    if pub_bytes != kid_pub:
+        raise ValueError("kid_pub does not match the public key of ed25519_priv")
+
+    subject = issuer = x509.Name(
+        [x509.NameAttribute(NameOID.COMMON_NAME, f"hm-kid-{kid_pub.hex()[:16]}")]
+    )
+
+    now = _dt.datetime.now(_dt.UTC)
+    san = x509.SubjectAlternativeName([x509.OtherName(ID_HM_KID_OID, _der_octet_string(kid_pub))])
+
+    cert = (
+        x509.CertificateBuilder()
+        .subject_name(subject)
+        .issuer_name(issuer)
+        .public_key(pub)
+        .serial_number(x509.random_serial_number())
+        .not_valid_before(now - _dt.timedelta(minutes=1))
+        .not_valid_after(now + _dt.timedelta(days=valid_days))
+        .add_extension(san, critical=False)
+        .add_extension(
+            x509.BasicConstraints(ca=True, path_length=None),
+            critical=True,
+        )
+        .sign(private_key=ed25519_priv, algorithm=None)
+    )
+    return cert.public_bytes(serialization.Encoding.PEM)
+
+
+def _der_octet_string(value: bytes) -> bytes:
+    """Wrap `value` as a DER OCTET STRING (tag 0x04)."""
+    if len(value) < 0x80:
+        return bytes([0x04, len(value)]) + value
+    # 32-byte kid is always short-form; longer values not expected here.
+    raise ValueError("kid value too large for short-form DER")  # pragma: no cover
+
+
+def extract_kid_from_cert(cert_pem: bytes) -> bytes:
+    """Return the 32-byte kid embedded via SAN OID `id-hm-kid`.
+
+    Falls back to the certificate's Ed25519 SubjectPublicKey when the
+    SAN extension is absent; raises `TLSProfileError` if neither path
+    yields a 32-byte kid.
+    """
+    cert = x509.load_pem_x509_certificate(cert_pem)
+    try:
+        san = cert.extensions.get_extension_for_class(x509.SubjectAlternativeName).value
+    except x509.ExtensionNotFound:
+        san = None
+
+    if san is not None:
+        for general_name in san:
+            if isinstance(general_name, x509.OtherName) and general_name.type_id == ID_HM_KID_OID:
+                raw = general_name.value
+                # Strip the DER OCTET STRING wrapper if present.
+                if len(raw) == 34 and raw[0] == 0x04 and raw[1] == 32:
+                    return bytes(raw[2:])
+                if len(raw) == 32:
+                    return bytes(raw)
+                raise TLSProfileError(f"id-hm-kid SAN value has unexpected length {len(raw)}")
+
+    # Fallback: derive kid from the SPKI (RPK shape). Only valid for
+    # Ed25519 SPKIs — anything else means the kid binding is missing.
+    pub = cert.public_key()
+    if isinstance(pub, ed25519.Ed25519PublicKey):
+        return pub.public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        )
+    raise TLSProfileError("certificate does not carry an id-hm-kid SAN or Ed25519 SPKI")
+
+
+def ed25519_priv_from_secret(secret_bytes: bytes) -> ed25519.Ed25519PrivateKey:
+    """Adapter: construct a `cryptography` Ed25519 private key from the
+    raw 32-byte secret stored on `Keypair.secret_bytes` (or its
+    composite-key prefix). Used by the TCP transport when wrapping a
+    socket with TLS.
+    """
+    return ed25519.Ed25519PrivateKey.from_private_bytes(secret_bytes[:32])

hypermind/types.py

@@ -0,0 +1,59 @@
+"""Public type re-exports — canonical location as of v0.5.
+
+Per ROADMAP §0.5.4–0.5.8 (WS-F DX cleanup), the public surface is
+consolidating around three namespaces:
+
+  - ``hypermind`` — top-level (``HyperMindAgent``, ``Claim``, ``Dispute``,
+    ``Capability``, ``Caveat``, ``Blocked``, ``BlockReason``,
+    ``__version__``, ``open``).
+  - ``hypermind.types`` — every supporting dataclass / Literal / Protocol
+    needed to type-annotate calls into the SDK (this module).
+  - ``hypermind.testing`` — fixtures and cohort factories used by tests
+    (``testbed_cohort`` lives here as of v0.5).
+
+The root re-exports retained for v0.5/v0.6 fire ``PendingDeprecationWarning``
+on first attribute lookup; they will become ``DeprecationWarning`` in
+v0.7 and are scheduled for removal in v1.0. New code SHOULD import from
+this module directly:
+
+.. code-block:: python
+
+    from hypermind.types import ClaimType, RouteStrategy, Subscription
+"""
+
+from __future__ import annotations
+
+from hypermind.agent import (
+    BlockReason,
+    ClaimEvent,
+    ClaimType,
+    VouchRequest,
+)
+from hypermind.consult import (
+    ArgumentDAG,
+    ArgumentEdge,
+    CalibTruthSnapshot,
+    PanelMember,
+    RouteStrategy,
+)
+from hypermind.dispute import DisputeStatus
+from hypermind.pin_policy import PinPolicy
+from hypermind.transport.bus import Subscription
+from hypermind.wire import Kid, SignedStatement
+
+__all__ = [
+    "ArgumentDAG",
+    "ArgumentEdge",
+    "BlockReason",
+    "CalibTruthSnapshot",
+    "ClaimEvent",
+    "ClaimType",
+    "DisputeStatus",
+    "Kid",
+    "PanelMember",
+    "PinPolicy",
+    "RouteStrategy",
+    "SignedStatement",
+    "Subscription",
+    "VouchRequest",
+]

hypermind/uncertainty.py

@@ -0,0 +1,222 @@
+"""First-class `Uncertainty` type — RECEIPT.uncertainty triple semantics.
+
+Wei-Chen Cycle 2 §5: encodes first- and second-order uncertainty so the
+v0.2 Correlated-Agreement peer-prediction layer can score reports
+without forklift. v0.1 emits the field; v0.2 scores it.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+
+@dataclass(frozen=True)
+class Uncertainty:
+    """Posterior uncertainty over a claim's truth value.
+
+    `epistemic_var` (model uncertainty, BALD-style) is what drives
+    information-gain routing in v0.2. `aleatoric_var` (irreducible
+    noise) bounds CA payment — claims with high aleatoric var yield
+    bounded peer-prediction reward to prevent reward-hacking.
+    """
+
+    kind: Literal["beta", "dirichlet", "gauss"]
+    params: tuple[float, ...]
+    epistemic_var: float = 0.0
+    aleatoric_var: float = 0.0
+    n_effective: float = 1.0
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.kind == "beta" and len(self.params) != 2:
+            raise ValueError("beta uncertainty needs (alpha, beta)")
+        if self.kind == "gauss" and len(self.params) != 2:
+            raise ValueError("gauss uncertainty needs (mu, sigma_squared)")
+        if self.kind == "dirichlet" and len(self.params) < 2:
+            raise ValueError("dirichlet uncertainty needs ≥2 alphas")
+        if self.epistemic_var < 0 or self.aleatoric_var < 0:
+            raise ValueError("variances must be non-negative")
+        if self.n_effective <= 0:
+            raise ValueError("n_effective must be positive")
+
+    # ---- constructors ----------------------------------------------------
+
+    @classmethod
+    def beta(cls, alpha: float, beta: float, *, n_eff: float | None = None) -> Uncertainty:
+        if alpha <= 0 or beta <= 0:
+            raise ValueError(
+                f"beta params must be positive (got alpha={alpha}, beta={beta}).\n"
+                f"  Hint: use Uncertainty.unknown() if you have no prior, or "
+                f"alpha=successes+1, beta=failures+1 for Laplace-smoothed counts."
+            )
+        n = n_eff if n_eff is not None else alpha + beta
+        var = (alpha * beta) / ((alpha + beta) ** 2 * (alpha + beta + 1))
+        return cls(
+            kind="beta",
+            params=(float(alpha), float(beta)),
+            epistemic_var=var,
+            aleatoric_var=0.0,
+            n_effective=float(n),
+        )
+
+    @classmethod
+    def unknown(cls) -> Uncertainty:
+        """The 'I have no prior' default — Beta(1, 1), uniform on [0, 1].
+
+        Use this when publishing a claim before any evidence has been
+        gathered. The reputation kernel treats this as a non-informative
+        report; oracle resolution will move the posterior decisively.
+        """
+        return cls.beta(1, 1)
+
+    @classmethod
+    def point(cls, p: float, *, n_eff: float = 1.0) -> Uncertainty:
+        """A near-delta posterior at probability `p` ∈ [0, 1].
+
+        Use this for confident-but-fallible point claims. Internally
+        encodes as Beta(α, β) with α + β = n_eff and mean ≈ p.
+        """
+        if not 0.0 <= p <= 1.0:
+            raise ValueError(
+                f"point probability must be in [0, 1] (got {p}).\n"
+                f"  Hint: Uncertainty.point(p) takes a probability, not log-odds."
+            )
+        # Tiny offsets keep params strictly positive while the mean stays at p.
+        alpha = max(p * n_eff, 1e-3)
+        beta = max((1 - p) * n_eff, 1e-3)
+        return cls.beta(alpha, beta, n_eff=n_eff)
+
+    @classmethod
+    def dirichlet(cls, alphas: tuple[float, ...]) -> Uncertainty:
+        alphas = tuple(float(a) for a in alphas)
+        if any(a <= 0 for a in alphas):
+            raise ValueError("dirichlet alphas must be positive")
+        a0 = sum(alphas)
+        # variance of marginal = α_i * (a0 - α_i) / (a0² * (a0 + 1))
+        var = sum(a * (a0 - a) / (a0**2 * (a0 + 1)) for a in alphas) / len(alphas)
+        return cls(
+            kind="dirichlet",
+            params=alphas,
+            epistemic_var=var,
+            aleatoric_var=0.0,
+            n_effective=a0,
+        )
+
+    @classmethod
+    def gauss(cls, mu: float, sigma2: float, *, n_eff: float = 1.0) -> Uncertainty:
+        if sigma2 < 0:
+            raise ValueError("gauss variance must be non-negative")
+        return cls(
+            kind="gauss",
+            params=(float(mu), float(sigma2)),
+            epistemic_var=float(sigma2),
+            aleatoric_var=0.0,
+            n_effective=float(n_eff),
+        )
+
+    @classmethod
+    def from_logits(
+        cls,
+        logits: list[float],
+        *,
+        temperature: float = 1.0,
+        deep_ensemble: list[list[float]] | None = None,
+    ) -> Uncertainty:
+        """Convert classifier logits to a Dirichlet posterior.
+
+        If `deep_ensemble` is provided, epistemic_var is the disagreement
+        across ensemble members (BALD-style); otherwise epistemic_var is
+        the marginal variance and aleatoric_var is set to 0.
+        """
+        scaled = [logit / temperature for logit in logits]
+        m = max(scaled)
+        exps = [math.exp(x - m) for x in scaled]
+        z = sum(exps)
+        probs = [e / z for e in exps]
+        # Pseudo-counts: one effective observation per logit dimension.
+        alphas = tuple(max(p * len(probs) + 1.0, 0.5) for p in probs)
+        u = cls.dirichlet(alphas)
+        if deep_ensemble:
+            ens_probs = []
+            for ens_logits in deep_ensemble:
+                m2 = max(ens_logits)
+                exps2 = [math.exp(x - m2) for x in ens_logits]
+                z2 = sum(exps2)
+                ens_probs.append([e / z2 for e in exps2])
+            mean_probs = [
+                sum(ep[i] for ep in ens_probs) / len(ens_probs) for i in range(len(probs))
+            ]
+            ens_var = sum(
+                sum((ep[i] - mean_probs[i]) ** 2 for ep in ens_probs) / len(ens_probs)
+                for i in range(len(probs))
+            ) / len(probs)
+            u = cls(
+                kind=u.kind,
+                params=u.params,
+                epistemic_var=ens_var,
+                aleatoric_var=u.epistemic_var,
+                n_effective=u.n_effective,
+            )
+        return u
+
+    # ---- scoring ---------------------------------------------------------
+
+    def mean(self) -> float:
+        if self.kind == "beta":
+            a, b = self.params
+            return a / (a + b)
+        if self.kind == "gauss":
+            return self.params[0]
+        if self.kind == "dirichlet":
+            a0 = sum(self.params)
+            # Mean of last dimension as the "positive" class (convention).
+            return self.params[-1] / a0
+        raise ValueError(f"unknown kind {self.kind}")
+
+    def brier(self, outcome: int) -> float:
+        """Brier score against a binary outcome (lower = better)."""
+        if outcome not in (0, 1):
+            raise ValueError("brier outcome must be 0 or 1")
+        return (self.mean() - outcome) ** 2
+
+    def log_score(self, outcome: int) -> float:
+        """Log-loss against a binary outcome (lower = better)."""
+        p = self.mean()
+        # avoid log(0)
+        p = min(max(p, 1e-9), 1 - 1e-9)
+        return -math.log(p if outcome == 1 else 1 - p)
+
+    # ---- wire serialization ----------------------------------------------
+
+    def __repr__(self) -> str:
+        if self.kind == "beta":
+            a, b = self.params
+            return f"Uncertainty.beta(α={a:g}, β={b:g}, mean={self.mean():.3f}, var={self.epistemic_var:.4f})"
+        if self.kind == "gauss":
+            mu, s2 = self.params
+            return f"Uncertainty.gauss(μ={mu:g}, σ²={s2:.4f}, n_eff={self.n_effective:g})"
+        if self.kind == "dirichlet":
+            return f"Uncertainty.dirichlet(α={tuple(round(p, 3) for p in self.params)}, n_eff={self.n_effective:g})"
+        return f"Uncertainty(kind={self.kind!r}, params={self.params!r})"
+
+    def to_cbor(self) -> dict:
+        """COSE protected header label -65608 payload."""
+        return {
+            "kind": self.kind,
+            "params": list(self.params),
+            "epistemic_var": self.epistemic_var,
+            "aleatoric_var": self.aleatoric_var,
+            "n_effective": self.n_effective,
+        }
+
+    @classmethod
+    def from_cbor(cls, m: dict) -> Uncertainty:
+        return cls(
+            kind=m["kind"],
+            params=tuple(m["params"]),
+            epistemic_var=float(m.get("epistemic_var", 0.0)),
+            aleatoric_var=float(m.get("aleatoric_var", 0.0)),
+            n_effective=float(m.get("n_effective", 1.0)),
+        )