hypermind 0.11.0__py3-none-any.whl

hypermind/capability.py

@@ -0,0 +1,923 @@
+"""Capability tokens with caveat-chain attenuation.
+
+Biscuit-shape semantics (monotonic narrowing) bound by COSE signature.
+Closes Cycle-1 fix #5 and the MCP confused-deputy gap (§4.12.2).
+
+Chain-of-trust binding (closes self-heal Cycle-1 Finding #1):
+  - Each token records `root_issuer` (the first issuer in the chain).
+  - Each attenuation records `parent_sig` (a hash of the parent's
+    canonical body+sig). The attenuated token's signed body therefore
+    proves "this attenuation was performed on a token whose body+sig
+    hash to `parent_sig`" — verifiers walk the chain back to a
+    recognised root issuer.
+  - `verify()` requires `expected_root_issuer` to be supplied so the
+    caller pins which root they trust; verifying without one only
+    checks self-consistency, NOT trust.
+
+Each caveat narrows scope; first failing caveat raises AuthError with
+`failed_caveat=<kind>` so operators can see exactly which restriction
+fired. The caveat list and signing alg are inside the signed preimage
+(A-ALG-BOUND), so JWT-`alg=none`-class substitution is impossible.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from dataclasses import dataclass, field
+from datetime import UTC
+from typing import TYPE_CHECKING, Any, Literal
+
+import cbor2
+
+from hypermind.crypto.signing import Keypair, verify_ed25519
+from hypermind.errors import AuthError, ConformanceError
+from hypermind.revocation import RevocationStore
+
+if TYPE_CHECKING:
+    from hypermind.revocation import RevocationList
+
+CaveatKind = Literal[
+    "topic",
+    "claim_type",
+    "rate",
+    "expiry",
+    "parent_kid",
+    "tool",
+    "ns",
+    "room",
+    "to",
+]
+
+#: Closed set of valid caveat kinds (validated in `Caveat.__post_init__`).
+#: `ns`, `room`, `to` were added at wire-version 2 per spec §25.1.
+_VALID_CAVEAT_KINDS: frozenset[str] = frozenset(
+    {
+        "topic",
+        "claim_type",
+        "rate",
+        "expiry",
+        "parent_kid",
+        "tool",
+        "ns",
+        "room",
+        "to",
+    }
+)
+
+
+# -----------------------------------------------------------------------
+# TokenBucket — runtime rate enforcement for "rate" caveats (P1-03)
+# -----------------------------------------------------------------------
+
+
+class TokenBucket:
+    """Leaky-bucket / token-bucket for rate-caveat enforcement.
+
+    Accepts rate strings in the forms used by ``Caveat.rate()``:
+    ``"5/min"``, ``"100/hour"``, ``"10/s"`` (also ``"sec"``, ``"second"``,
+    ``"minute"``, ``"hr"``).
+
+    Thread-safety: not thread-safe by itself; the caller (``_require_cap``)
+    holds a per-agent dict, which is already single-threaded inside the
+    async event loop.
+    """
+
+    def __init__(self, rate_str: str) -> None:
+        try:
+            per_min = _rate_per_min(rate_str)
+        except (ValueError, TypeError) as exc:
+            raise AuthError(
+                f"unparsable rate caveat {rate_str!r}: {exc}",
+                failed_caveat="rate",
+            ) from exc
+        # Capacity = max(1, per-second rate) burst tokens pre-filled at start.
+        self._refill_per_second: float = per_min / 60.0
+        self._capacity: float = max(1.0, per_min / 60.0)
+        self._tokens: float = self._capacity
+        self._last_refill: float = time.monotonic()
+
+    def consume(self) -> bool:
+        """Try to consume one token.  Returns True if allowed, False if limited."""
+        now = time.monotonic()
+        elapsed = now - self._last_refill
+        self._last_refill = now
+        self._tokens = min(self._capacity, self._tokens + elapsed * self._refill_per_second)
+        if self._tokens >= 1.0:
+            self._tokens -= 1.0
+            return True
+        return False
+
+
+@dataclass(frozen=True)
+class Caveat:
+    """A single restriction in a caveat chain. Caveats are ordered;
+    each subsequent caveat may only narrow the scope of its predecessors.
+
+    Valid `kind` values are validated at construction (closes the silent
+    typo bypass — `Caveat("topik", ...)` previously parsed but never
+    enforced anything). Use the named constructors (`Caveat.topic(...)`,
+    `Caveat.rate(...)`, etc.) to avoid hand-typing the kind string.
+    """
+
+    kind: CaveatKind
+    value: Any
+
+    def __post_init__(self) -> None:
+        if self.kind not in _VALID_CAVEAT_KINDS:
+            raise ValueError(
+                f"unknown caveat kind {self.kind!r}.\n"
+                f"  Valid kinds: {sorted(_VALID_CAVEAT_KINDS)}\n"
+                f"  Hint: use Caveat.topic(...), Caveat.rate(...), "
+                f"Caveat.namespace(...), Caveat.room(...), Caveat.recipient(...) "
+                f"to avoid typos."
+            )
+
+    # ---- named constructors (typo-proof) -------------------------------
+
+    @classmethod
+    def topic(cls, glob: str) -> Caveat:
+        """Restrict to a topic glob, e.g. 'ai-safety/*' or 'finance/eval'."""
+        return cls(kind="topic", value=glob)
+
+    @classmethod
+    def claim_type(cls, name: str) -> Caveat:
+        """Restrict to a claim_type, e.g. 'eval_result' or 'threat_indicator'."""
+        return cls(kind="claim_type", value=name)
+
+    @classmethod
+    def rate(cls, spec: str) -> Caveat:
+        """Restrict invocation rate, e.g. '10/min', '60/sec', '1000/hr'."""
+        return cls(kind="rate", value=spec)
+
+    @classmethod
+    def expiry(cls, iso_timestamp: str) -> Caveat:
+        """Expire after the ISO-8601 timestamp (UTC, e.g. '2030-01-01T00:00Z')."""
+        return cls(kind="expiry", value=iso_timestamp)
+
+    @classmethod
+    def parent_kid(cls, kid: bytes | str) -> Caveat:
+        """Pin to a specific parent claim kid (32-byte hex or bytes)."""
+        return cls(kind="parent_kid", value=kid.hex() if isinstance(kid, bytes) else kid)
+
+    @classmethod
+    def tool(cls, name: str) -> Caveat:
+        """Restrict to a specific MCP tool, e.g. 'web_search' or 'shell'."""
+        return cls(kind="tool", value=name)
+
+    @classmethod
+    def namespace(cls, ns_id_hex: str) -> Caveat:
+        """Restrict to a HyperMind namespace (spec §25.1).
+
+        ``ns_id_hex`` is the lowercase hex of the namespace_id. At
+        wire-version 2 every CapToken root MUST carry one of these.
+        """
+        if not isinstance(ns_id_hex, str):
+            raise ValueError("namespace caveat value must be a hex string")
+        return cls(kind="ns", value=ns_id_hex.lower())
+
+    @classmethod
+    def room(cls, room_id: str) -> Caveat:
+        """Restrict to a TAL Room id (spec §25.1).
+
+        ``room_id`` is the hex of the Room id (a Room lives inside a
+        namespace; the `ns:` caveat carries the namespace anchor).
+        """
+        if not isinstance(room_id, str):
+            raise ValueError("room caveat value must be a hex string")
+        return cls(kind="room", value=room_id.lower())
+
+    @classmethod
+    def recipient(cls, kid: bytes | str) -> Caveat:
+        """Restrict to a specific recipient kid (spec §25.1).
+
+        Used for consult routing or encrypted-payload addressing —
+        only the named recipient kid may be the operation target.
+        """
+        if isinstance(kid, (bytes, bytearray)):
+            value = bytes(kid).hex()
+        elif isinstance(kid, str):
+            value = kid.lower()
+        else:
+            raise ValueError("recipient caveat value must be bytes or hex string")
+        return cls(kind="to", value=value)
+
+    def to_cbor(self) -> dict[str, Any]:
+        return {"kind": self.kind, "value": self.value}
+
+    @classmethod
+    def from_cbor(cls, m: dict[str, Any]) -> Caveat:
+        return cls(kind=m["kind"], value=m["value"])
+
+
+@dataclass
+class CapToken:
+    """Capability token with Biscuit-shape caveat-chain attenuation (spec §4.12).
+
+    A CapToken is minted by an issuer, optionally attenuated (narrowed) by
+    delegates, and presented at the point of use. The caveat list and signing
+    algorithm are bound inside the COSE signature (A-ALG-BOUND), making
+    JWT-``alg=none``-class substitution impossible. Only the current
+    ``subject`` may attenuate — any other signer is rejected.
+
+    Examples:
+        >>> from hypermind.capability import CapToken, Caveat
+        >>> token = CapToken.mint(
+        ...     issuer_keypair=alice.keypair,
+        ...     subject=bob.keypair.kid,
+        ...     caveats=[Caveat.topic("ai-safety/*"), Caveat.rate("10/min")],
+        ... )
+        >>> delegated = token.attenuate(
+        ...     new_subject=carol.keypair.kid,
+        ...     extra_caveats=[Caveat.expiry("2030-01-01T00:00Z")],
+        ...     signing_keypair=bob.keypair,
+        ... )
+        >>> delegated.verify(action="publish_claim", topic="ai-safety/eval")
+    """
+
+    issuer: bytes
+    subject: bytes
+    caveats: list[Caveat]
+    sig: bytes = b""
+    issued_at_ms: int = field(default_factory=lambda: int(time.time() * 1000))
+    root_issuer: bytes = b""
+    parent_sig: bytes = b""  # hash of parent's _canonical_body()+sig; b"" for root
+
+    # Private mint-namespace marker for v0/v1 grandfathering (spec §25.3).
+    # Set at mint() time; never serialised. Verifiers receiving a v1 token
+    # in a different namespace MUST reject it (BlockReason CASCADE-L5-CROSS-NS-V1).
+    # Prefixed with `_` so dataclass equality / serialisation are unaffected.
+    _mint_namespace: bytes | None = field(default=None, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        if not self.root_issuer:
+            # A root token's own issuer IS the root.
+            self.root_issuer = self.issuer
+
+    @classmethod
+    def mint(
+        cls,
+        *,
+        issuer_keypair: Keypair,
+        subject: bytes,
+        caveats: list[Caveat] | None = None,
+        wire_version: int = 1,
+        namespace_id: bytes | None = None,
+    ) -> CapToken:
+        """Mint a new ROOT capability token. Use `attenuate()` to delegate.
+
+        Spec §25.2: at ``wire_version >= 2``, every CapToken root MUST carry
+        an explicit ``ns:<namespace_id_hex>`` caveat. ``mint`` will raise
+        ``ValueError`` if neither the caveat nor a ``namespace_id`` argument
+        is supplied (the argument is auto-converted to an ``ns`` caveat
+        when present).
+
+        For ``wire_version <= 1`` (legacy / grandfathered), the optional
+        ``namespace_id`` is recorded as the token's mint namespace
+        (``_mint_namespace``) so verifiers can enforce §25.3
+        cross-namespace rejection without requiring the caveat itself.
+        """
+        cavs = list(caveats or [])
+        existing_ns = next((c for c in cavs if c.kind == "ns"), None)
+
+        if wire_version >= 2:
+            if existing_ns is None:
+                if namespace_id is None:
+                    raise ValueError(
+                        "wire_version>=2 CapTokens MUST carry an `ns` caveat "
+                        "(spec §25.2). Pass namespace_id=... or include "
+                        "Caveat.namespace(...) in caveats."
+                    )
+                cavs.insert(0, Caveat.namespace(namespace_id.hex()))
+                existing_ns = cavs[0]
+            elif namespace_id is not None and existing_ns.value != namespace_id.hex():
+                raise ValueError(
+                    f"namespace_id={namespace_id.hex()!r} disagrees with "
+                    f"explicit ns caveat {existing_ns.value!r}"
+                )
+
+        token = cls(
+            issuer=issuer_keypair.kid,
+            subject=subject,
+            caveats=cavs,
+            root_issuer=issuer_keypair.kid,
+            parent_sig=b"",
+        )
+        # Record mint namespace for grandfathering (§25.3).
+        if existing_ns is not None:
+            try:
+                token._mint_namespace = bytes.fromhex(str(existing_ns.value))
+            except ValueError:
+                token._mint_namespace = None
+        elif namespace_id is not None:
+            token._mint_namespace = bytes(namespace_id)
+        token.sig = issuer_keypair.sign(token._canonical_body())
+        return token
+
+    def attenuate(self, *new_caveats: Caveat, signing_keypair: Keypair) -> CapToken:
+        """Re-sign with additional caveats binding back to this parent.
+
+        The signing principal MUST be the current `subject` (the holder
+        delegating onward). Every new caveat — whether the same kind or
+        a brand-new kind — must be a strict narrowing of the existing
+        chain; new caveats CANNOT widen scope by omitting an existing
+        kind, and a new kind not present in the parent is unrestricted
+        UNLESS combined with an explicit narrowing of the same kind.
+
+        The new token carries `parent_sig` = hash(parent body || parent
+        sig) so chain-walk verification can confirm the parent was
+        intact at delegation time.
+        """
+        if signing_keypair.kid != self.subject:
+            raise AuthError(
+                "only the current subject may attenuate a capability",
+                failed_caveat="subject",
+            )
+
+        for c in new_caveats:
+            self._assert_narrows(c)
+
+        merged_caveats = list(self.caveats) + list(new_caveats)
+        parent_fp = _fingerprint(self._canonical_body() + self.sig)
+        token = CapToken(
+            issuer=signing_keypair.kid,
+            subject=self.subject,
+            caveats=merged_caveats,
+            root_issuer=self.root_issuer,
+            parent_sig=parent_fp,
+        )
+        # Inherit mint-namespace marker from parent (grandfathering §25.3).
+        token._mint_namespace = self._mint_namespace
+        token.sig = signing_keypair.sign(token._canonical_body())
+        return token
+
+    def _assert_narrows(self, new: Caveat) -> None:
+        """A caveat must be at least as restrictive as every same-kind
+        caveat already in the chain. A new caveat of a previously-unseen
+        kind is allowed (it adds a fresh restriction, never widens)."""
+        for existing in self.caveats:
+            if existing.kind != new.kind:
+                continue
+            if existing.kind == "rate":
+                if _rate_per_min(new.value) > _rate_per_min(existing.value):
+                    raise AuthError(
+                        f"rate caveat must narrow: {new.value} > {existing.value}",
+                        failed_caveat="rate",
+                    )
+            elif existing.kind == "expiry":
+                if _parse_iso_to_ms(str(new.value)) > _parse_iso_to_ms(str(existing.value)):
+                    raise AuthError(
+                        f"expiry caveat must narrow: {new.value} > {existing.value}",
+                        failed_caveat="expiry",
+                    )
+            elif existing.kind in ("topic", "claim_type", "tool"):
+                if not _is_topic_subset(new.value, existing.value):
+                    raise AuthError(
+                        f"{existing.kind} caveat must narrow",
+                        failed_caveat=existing.kind,
+                    )
+            elif existing.kind == "parent_kid":
+                if str(new.value) != str(existing.value):
+                    raise AuthError(
+                        "parent_kid caveat is exact-match; cannot change",
+                        failed_caveat="parent_kid",
+                    )
+            elif existing.kind in ("ns", "room", "to"):
+                if str(new.value) != str(existing.value):
+                    raise AuthError(
+                        f"{existing.kind} caveat is exact-match; cannot change",
+                        failed_caveat=existing.kind,
+                    )
+
+    def _ns_caveat_value(self) -> str | None:
+        """Return the `ns:` caveat value (lowercase hex) or None."""
+        for c in self.caveats:
+            if c.kind == "ns":
+                return str(c.value).lower()
+        return None
+
+    def _check_namespace_gate(self, wire_version: int, current_namespace_id: bytes | None) -> bool:
+        """Spec §25.2 / §25.3 — namespace gating for verify_chain.
+
+        - wire_version >= 2: token MUST carry an `ns` caveat. If
+          ``current_namespace_id`` is supplied, the caveat value MUST
+          match it (lowercase hex). Mismatch ⇒ False.
+        - wire_version <= 1: legacy / grandfathered. If
+          ``current_namespace_id`` is supplied AND the token has a
+          recorded mint namespace (or explicit `ns` caveat), they must
+          match — otherwise reject (spec §25.3, BlockReason
+          ``CASCADE-L5-CROSS-NS-V1``).
+        """
+        ns_caveat = self._ns_caveat_value()
+        if wire_version >= 2:
+            if ns_caveat is None:
+                return False
+            if current_namespace_id is not None:
+                if ns_caveat != current_namespace_id.hex().lower():
+                    return False
+            return True
+        # wire_version <= 1
+        if current_namespace_id is None:
+            return True
+        if ns_caveat is not None:
+            return ns_caveat == current_namespace_id.hex().lower()
+        if self._mint_namespace is not None:
+            return bytes(self._mint_namespace) == bytes(current_namespace_id)
+        # No mint-namespace recorded and no caveat: cannot prove origin.
+        # Caller has pinned a namespace, so refuse conservatively.
+        return False
+
+    def _canonical_body(self) -> bytes:
+        """The canonical signed preimage. Includes root_issuer +
+        parent_sig so substitution attacks cannot forge a fake chain."""
+        return cbor2.dumps(
+            {
+                "issuer": self.issuer,
+                "subject": self.subject,
+                "caveats": [c.to_cbor() for c in self.caveats],
+                "issued_at_ms": self.issued_at_ms,
+                "root_issuer": self.root_issuer,
+                "parent_sig": self.parent_sig,
+            },
+            canonical=True,
+        )
+
+    def to_bytes(self) -> bytes:
+        """Serialize as deterministic CBOR (RFC 8949 §4.2)."""
+        return cbor2.dumps(
+            {
+                "issuer": self.issuer,
+                "subject": self.subject,
+                "caveats": [c.to_cbor() for c in self.caveats],
+                "issued_at_ms": self.issued_at_ms,
+                "root_issuer": self.root_issuer,
+                "parent_sig": self.parent_sig,
+                "sig": self.sig,
+            },
+            canonical=True,
+        )
+
+    @classmethod
+    def from_bytes(cls, raw: bytes) -> CapToken:
+        """Parse a CapToken from canonical CBOR.
+
+        Enforces the same A-ALG-BOUND-style canonical-encoding gate as
+        `SignedStatement.from_bytes()`: parse, re-encode under
+        deterministic CBOR, and require byte-equality with the wire
+        bytes. Rejects non-canonical inputs (reordered map keys,
+        indefinite-length strings, alternative integer encodings) at
+        parse time so a single logical token cannot have two distinct
+        wire encodings (and thus two distinct fingerprints).
+        """
+        try:
+            m = cbor2.loads(raw)
+        except cbor2.CBORDecodeError as e:
+            raise ConformanceError(f"capability token is not valid CBOR: {e}") from e
+        if not isinstance(m, dict):
+            raise ConformanceError("capability token must be a CBOR map")
+        if cbor2.dumps(m, canonical=True) != raw:
+            raise ConformanceError("capability token is not canonical CBOR (RFC 8949 §4.2)")
+        try:
+            token = cls(
+                issuer=bytes(m["issuer"]),
+                subject=bytes(m["subject"]),
+                caveats=[Caveat.from_cbor(c) for c in m["caveats"]],
+                sig=bytes(m["sig"]),
+                issued_at_ms=int(m["issued_at_ms"]),
+                root_issuer=bytes(m["root_issuer"]),
+                parent_sig=bytes(m["parent_sig"]),
+            )
+        except (KeyError, TypeError) as e:
+            raise ConformanceError(f"capability token missing/invalid field: {e}") from e
+        return token
+
+    def verify(self, *, expected_root_issuer: bytes | None = None) -> bool:
+        """Verify the issuer's signature.
+
+        If `expected_root_issuer` is supplied, also verify that
+        `self.root_issuer == expected_root_issuer`. Without that pin,
+        verification only proves self-consistency, NOT that the chain
+        traces back to a trusted authority — callers MUST supply the
+        expected root in any security-relevant context.
+        """
+        if expected_root_issuer is not None and self.root_issuer != expected_root_issuer:
+            return False
+        return verify_ed25519(self.issuer, self.sig, self._canonical_body())
+
+    def verify_chain(
+        self,
+        parent: CapToken | None,
+        *,
+        revocation_list: RevocationList | None = None,
+        wire_version: int = 1,
+        current_namespace_id: bytes | None = None,
+    ) -> bool:
+        """Verify the leaf's own signature AND the chain link to `parent`.
+
+        Closes Cycle-2 Finding #3: earlier versions skipped the leaf's
+        own signature, allowing an unsigned token to pass `verify_chain`
+        if its `parent_sig` field happened to match. Now the leaf's
+        signature is checked first; only then is the parent link verified.
+
+        - Root token (`parent=None`): requires `parent_sig == b""` and
+          `issuer == root_issuer`.
+        - Delegated token: requires the parent's signature is valid,
+          `parent.subject == self.issuer`, root_issuer matches,
+          `self.parent_sig` == hash(parent body || parent sig), and
+          every same-kind caveat in self is a strict narrowing of the
+          parent's same-kind caveat (defence-in-depth: even if a
+          forged token bypassed `attenuate()`'s narrowing checks, a
+          chain walk catches scope widening).
+
+        P2-06: if ``revocation_list`` is supplied, any token whose issuer
+        kid appears in the list (regardless of HLC — epoch check) raises
+        :class:`AuthError` with ``rule_id="HM-REV-001"``.  The check is
+        applied to both ``self`` and ``parent`` so a revoked delegator
+        cannot ride a still-valid leaf.
+        """
+        if not self.verify():
+            return False
+        # Spec §25.2 / §25.3: namespace gating.
+        if not self._check_namespace_gate(wire_version, current_namespace_id):
+            return False
+        if parent is None:
+            if revocation_list is not None:
+                _check_revocation_list(self.issuer, revocation_list)
+            return hmac.compare_digest(self.parent_sig, b"") and hmac.compare_digest(
+                self.issuer, self.root_issuer
+            )
+        if not parent.verify():
+            return False
+        if revocation_list is not None:
+            _check_revocation_list(self.issuer, revocation_list)
+            _check_revocation_list(parent.issuer, revocation_list)
+        if not hmac.compare_digest(parent.subject, self.issuer):
+            return False
+        if not hmac.compare_digest(parent.root_issuer, self.root_issuer):
+            return False
+        if not hmac.compare_digest(
+            self.parent_sig, _fingerprint(parent._canonical_body() + parent.sig)
+        ):
+            return False
+        return _caveats_narrow(parent.caveats, self.caveats)
+
+    def verify_chain_full(
+        self,
+        chain: list[CapToken] | None = None,
+        *,
+        expected_root_issuer: bytes | None = None,
+        revocation_store: RevocationStore | None = None,
+        hlc: tuple[int, int] | None = None,
+        wire_version: int = 1,
+        current_namespace_id: bytes | None = None,
+    ) -> bool:
+        """Walk the full chain root → … → self.
+
+        `chain` is the ordered list of ancestor tokens, root first, NOT
+        including `self`. For a root token, pass `[]` or `None`. Returns
+        True only if every link verifies (signature, parent_sig binding,
+        root_issuer consistency, and monotonic narrowing of caveats).
+
+        If `expected_root_issuer` is supplied, also checks that the
+        root's issuer kid matches — pinning the chain to a trusted root.
+
+        If `revocation_store` is supplied, every token's `issuer` kid is
+        checked against it at the supplied `hlc` (defaults to (0, 0) =
+        "now"; a more accurate value pins historical-claim immutability
+        — statements signed strictly before the revocation point remain
+        valid). Any revoked kid raises :class:`AuthError` with
+        ``failed_caveat='revoked'`` (rule_id ``HM-KEY-REVOKED-001``).
+        """
+        ancestors = list(chain or [])
+
+        def _check_revoked(token: CapToken) -> None:
+            if revocation_store is None:
+                return
+            entry = revocation_store.is_revoked(token.issuer, hlc or (0, 0))
+            if entry is not None:
+                raise AuthError(
+                    f"capability token issuer kid {token.issuer.hex()[:8]}… "
+                    f"has been revoked (reason={entry.reason}, "
+                    f"rule_id=HM-KEY-REVOKED-001)",
+                    failed_caveat="revoked",
+                )
+
+        if not ancestors:
+            if not self.verify_chain(
+                None,
+                wire_version=wire_version,
+                current_namespace_id=current_namespace_id,
+            ):
+                return False
+            if expected_root_issuer is not None and not hmac.compare_digest(
+                self.root_issuer, expected_root_issuer
+            ):
+                return False
+            _check_revoked(self)
+            return True
+
+        root = ancestors[0]
+        if not root.verify_chain(
+            None,
+            wire_version=wire_version,
+            current_namespace_id=current_namespace_id,
+        ):
+            return False
+        if expected_root_issuer is not None and not hmac.compare_digest(
+            root.root_issuer, expected_root_issuer
+        ):
+            return False
+        _check_revoked(root)
+
+        prev = root
+        for token in ancestors[1:]:
+            if not token.verify_chain(
+                prev,
+                wire_version=wire_version,
+                current_namespace_id=current_namespace_id,
+            ):
+                return False
+            _check_revoked(token)
+            prev = token
+        if not self.verify_chain(
+            prev,
+            wire_version=wire_version,
+            current_namespace_id=current_namespace_id,
+        ):
+            return False
+        _check_revoked(self)
+        return True
+
+    def authorize(
+        self,
+        *,
+        action: str,
+        topic: str | None = None,
+        claim_type: str | None = None,
+        tool: str | None = None,
+        parent_kid: bytes | None = None,
+        expected_root_issuer: bytes | None = None,
+        revocation_store: RevocationStore | None = None,
+        hlc: tuple[int, int] | None = None,
+        require_chain: bool = True,
+        room: str | None = None,
+        recipient: bytes | str | None = None,
+        namespace_id: bytes | None = None,
+        wire_version: int = 1,
+        rate_store: Any | None = None,
+    ) -> None:
+        """Check that this token authorizes the requested action.
+
+        Raises AuthError(failed_caveat=...) on first failing caveat.
+        Caveats are evaluated in order; the first failure is reported,
+        so operators can pinpoint which restriction fired without
+        guessing the chain semantics.
+
+        For chain-of-trust enforcement, supply `expected_root_issuer`
+        — the kid of the principal you trust at the root of the chain.
+
+        Root tokens (parent_sig == b"") are verified via verify_chain(None)
+        so the issuer == root_issuer invariant is always checked.
+
+        Delegated tokens (parent_sig != b""):
+        - When ``require_chain=True`` (the default): raises AuthError if the
+          caller has not first called ``verify_chain_full()`` on the ancestor
+          chain. Pass ``require_chain=True`` only after that check passes.
+          This enforces that the full chain (root → … → self) has been verified.
+        - When ``require_chain=False`` (opt-out, legacy callers only): falls
+          back to checking the leaf signature only. Does NOT verify the parent
+          chain — a forged delegated token with a valid leaf sig will pass.
+          Callers using this path should migrate to ``verify_chain_full()``.
+        """
+        if topic is not None and _normalize_topic(topic) is None:
+            raise AuthError("topic contains path-traversal components", failed_caveat="topic")
+
+        if self.parent_sig == b"":
+            if not self.verify_chain(
+                None,
+                wire_version=wire_version,
+                current_namespace_id=namespace_id,
+            ):
+                raise AuthError("capability chain invalid", failed_caveat="signature")
+            if expected_root_issuer is not None and self.root_issuer != expected_root_issuer:
+                raise AuthError("root_issuer mismatch", failed_caveat="signature")
+        else:
+            if require_chain:
+                raise AuthError(
+                    "delegated CapToken passed to authorize() without prior chain verification; "
+                    "call verify_chain_full() on the full ancestor chain first, then pass "
+                    "require_chain=True only after that check passes",
+                    failed_caveat="signature",
+                )
+            # DEPRECATED: leaf-only verification for delegated tokens.
+            # Does not verify the parent chain — use verify_chain_full() instead.
+            if not self.verify(expected_root_issuer=expected_root_issuer):
+                raise AuthError("capability signature invalid", failed_caveat="signature")
+
+        # Revocation check (HM-KEY-REVOKED-001). The leaf token's issuer
+        # is the immediate signer; if its kid is revoked at `hlc`, refuse
+        # the action. Callers wanting full-chain revocation should call
+        # ``verify_chain_full(..., revocation_store=, hlc=)`` explicitly.
+        if revocation_store is not None:
+            entry = revocation_store.is_revoked(self.issuer, hlc or (0, 0))
+            if entry is not None:
+                raise AuthError(
+                    f"capability token issuer kid {self.issuer.hex()[:8]}… "
+                    f"has been revoked (reason={entry.reason}, "
+                    f"rule_id=HM-KEY-REVOKED-001)",
+                    failed_caveat="revoked",
+                )
+            # Also check the root, so a revoked-at-root delegate cannot
+            # ride on a still-active leaf signature.
+            if self.root_issuer != self.issuer:
+                root_entry = revocation_store.is_revoked(self.root_issuer, hlc or (0, 0))
+                if root_entry is not None:
+                    raise AuthError(
+                        f"capability root_issuer kid {self.root_issuer.hex()[:8]}… "
+                        f"has been revoked (reason={root_entry.reason}, "
+                        f"rule_id=HM-KEY-REVOKED-001)",
+                        failed_caveat="revoked",
+                    )
+
+        now_ms = int(time.time() * 1000)
+        for cav in self.caveats:
+            if cav.kind == "expiry":
+                expiry_ms = _parse_iso_to_ms(str(cav.value))
+                if now_ms > expiry_ms:
+                    raise AuthError(f"capability expired at {cav.value}", failed_caveat="expiry")
+            elif cav.kind == "topic" and topic is not None:
+                if not _is_topic_subset(topic, str(cav.value)):
+                    raise AuthError(
+                        f"topic {topic!r} not in caveat {cav.value!r}",
+                        failed_caveat="topic",
+                    )
+            elif cav.kind == "claim_type" and claim_type is not None:
+                if not _is_topic_subset(claim_type, str(cav.value)):
+                    raise AuthError(
+                        f"claim_type {claim_type!r} not in caveat {cav.value!r}",
+                        failed_caveat="claim_type",
+                    )
+            elif cav.kind == "tool" and tool is not None:
+                if not _is_topic_subset(tool, str(cav.value)):
+                    raise AuthError(
+                        f"tool {tool!r} not in caveat {cav.value!r}",
+                        failed_caveat="tool",
+                    )
+            elif cav.kind == "parent_kid" and parent_kid is not None:
+                expected = bytes.fromhex(str(cav.value))
+                if parent_kid != expected:
+                    raise AuthError(
+                        "parent_kid does not match caveat",
+                        failed_caveat="parent_kid",
+                    )
+            elif cav.kind == "rate":
+                _rate_per_min(cav.value)  # validate format
+                if rate_store is not None:
+                    # Delegate enforcement to the caller-supplied store.
+                    limit = _rate_per_min(cav.value)
+                    token_key = self.sig[:16].hex() + ":" + action
+                    if hasattr(rate_store, "check") and not rate_store.check(token_key, limit):
+                        raise AuthError(
+                            f"rate limit {cav.value} exceeded for action {action!r}",
+                            failed_caveat="rate",
+                        )
+                # When rate_store is None, format validation passes but enforcement
+                # is the caller's responsibility (e.g. HyperMindAgent uses TokenBucket
+                # after authorize()). This is intentional: authorize() is stateless.
+            elif cav.kind == "ns" and namespace_id is not None:
+                if str(cav.value).lower() != namespace_id.hex().lower():
+                    raise AuthError(
+                        f"namespace {namespace_id.hex()!r} not in caveat {cav.value!r}",
+                        failed_caveat="ns",
+                    )
+            elif cav.kind == "room" and room is not None:
+                if str(cav.value).lower() != str(room).lower():
+                    raise AuthError(
+                        f"room {room!r} not in caveat {cav.value!r}",
+                        failed_caveat="room",
+                    )
+            elif cav.kind == "to" and recipient is not None:
+                expected_to = (
+                    bytes(recipient).hex()
+                    if isinstance(recipient, (bytes, bytearray))
+                    else str(recipient).lower()
+                )
+                if str(cav.value).lower() != expected_to:
+                    raise AuthError(
+                        f"recipient {expected_to!r} not in caveat {cav.value!r}",
+                        failed_caveat="to",
+                    )
+
+        _ = action  # rate-limit hookpoint; runtime tracks usage
+
+
+def _check_revocation_list(kid: bytes, revocation_list: RevocationList) -> None:
+    """P2-06: Raise AuthError if ``kid`` appears in the revocation list.
+
+    This is an epoch check: the presence of the kid in the list at all
+    is sufficient for rejection regardless of HLC (conservative policy —
+    once revoked, always revoked for capability chain verification).
+    Rule id: ``HM-REV-001``.
+    """
+    for entry in revocation_list.entries:
+        if bytes(entry.kid) == bytes(kid):
+            raise AuthError(
+                f"capability token issuer kid {kid.hex()[:8]}… "
+                f"has been revoked (reason={entry.reason}, rule_id=HM-REV-001)",
+                failed_caveat="revoked",
+            )
+
+
+def _fingerprint(b: bytes) -> bytes:
+    """SHA-256 over canonical bytes — used to bind parent → child."""
+    return hashlib.sha256(b).digest()
+
+
+def _caveats_narrow(parent_caveats: list[Caveat], child_caveats: list[Caveat]) -> bool:
+    """Child's caveat list must extend parent's prefix and only narrow.
+
+    `attenuate()` produces `child.caveats = parent.caveats + new_caveats`,
+    so a well-formed child has the parent's caveats as an exact prefix.
+    Each appended caveat must be a strict narrowing of any same-kind
+    caveat earlier in the chain (or introduce a fresh restriction kind).
+    """
+    if len(child_caveats) < len(parent_caveats):
+        return False
+    for i, p in enumerate(parent_caveats):
+        c = child_caveats[i]
+        if c.kind != p.kind or c.value != p.value:
+            return False
+    for added in child_caveats[len(parent_caveats) :]:
+        for existing in parent_caveats:
+            if existing.kind != added.kind:
+                continue
+            try:
+                if existing.kind == "rate":
+                    if _rate_per_min(added.value) > _rate_per_min(existing.value):
+                        return False
+                elif existing.kind == "expiry":
+                    if _parse_iso_to_ms(str(added.value)) > _parse_iso_to_ms(str(existing.value)):
+                        return False
+                elif existing.kind in ("topic", "claim_type", "tool"):
+                    if not _is_topic_subset(str(added.value), str(existing.value)):
+                        return False
+                elif existing.kind == "parent_kid":
+                    if str(added.value) != str(existing.value):
+                        return False
+                elif existing.kind in ("ns", "room", "to"):
+                    if str(added.value) != str(existing.value):
+                        return False
+            except (AuthError, ValueError):
+                return False
+    return True
+
+
+def _rate_per_min(spec: Any) -> float:
+    """Parse 'N/min' or 'N/sec' into per-minute float."""
+    s = str(spec)
+    n_str, _, unit = s.partition("/")
+    n = float(n_str)
+    unit = unit.strip()
+    if unit in ("min", "minute", ""):
+        return n
+    if unit in ("sec", "second"):
+        return n * 60
+    if unit in ("hr", "hour"):
+        return n / 60
+    raise AuthError(f"unparsable rate {spec!r}", failed_caveat="rate")
+
+
+def _normalize_topic(s: str) -> str | None:
+    """Return None if the topic contains path-traversal components."""
+    parts = s.split("/")
+    if any(p in (".", "..") for p in parts):
+        return None
+    return s
+
+
+def _is_topic_subset(child: str, parent: str) -> bool:
+    """Glob-style subset: parent='ai-safety/*' covers child='ai-safety/eval'."""
+    if _normalize_topic(child) is None:
+        return False
+    parent_check = parent.rstrip("*").rstrip("/") if parent.endswith("/*") else parent
+    if _normalize_topic(parent_check) is None:
+        return False
+    if parent == child:
+        return True
+    if parent.endswith("/*"):
+        return child.startswith(parent[:-1])
+    if parent == "*":
+        return True
+    return False
+
+
+def _parse_iso_to_ms(s: str) -> int:
+    from datetime import datetime
+
+    if s.endswith("Z"):
+        s = s[:-1] + "+00:00"
+    dt = datetime.fromisoformat(s)
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=UTC)
+    return int(dt.timestamp() * 1000)