capforge 0.4.0__py3-none-any.whl

capforge/_delegation.py

@@ -0,0 +1,83 @@
+"""Delegation logic for the ACM protocol.
+
+Creates a delegated ACM (child) from a parent ACM, enforcing that the
+child's capabilities are a strict subset of the parent's capabilities.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+
+from capforge._exceptions import ACMInvalidError
+from capforge._model import (
+    Capability,
+    Constraints,
+    _ACMModel,
+    _AgentInfo,
+)
+
+
+def delegate(
+    parent: _ACMModel,
+    child_spiffe_id: str,
+    child_capabilities: list[Capability],
+    ttl: int = 3600,
+    constraints: Constraints | None = None,
+) -> _ACMModel:
+    """Create a delegated ACM model with narrowed scope.
+
+    Parameters
+    ----------
+    parent:
+        The parent ACM model to delegate from.
+    child_spiffe_id:
+        SPIFFE ID for the child agent.
+    child_capabilities:
+        Capabilities to delegate. Must be a subset of the parent's.
+    ttl:
+        Time-to-live in seconds for the delegated ACM.
+    constraints:
+        Optional constraints for the child. If None, inherits from parent.
+        If provided, must be at least as restrictive as the parent's.
+
+    Returns
+    -------
+    _ACMModel
+        A new ACM model representing the delegated document.
+
+    Raises
+    ------
+    ACMInvalidError
+        If any child capability is not in the parent's capabilities.
+    """
+    parent_resource_actions: set[tuple[str, str]] = {
+        (c.resource, c.action) for c in parent.capabilities
+    }
+
+    for c in child_capabilities:
+        if (c.resource, c.action) not in parent_resource_actions:
+            msg = (
+                f"Capability '{c.resource}:{c.action}' not found in parent ACM. "
+                "Child capabilities must be a subset of parent capabilities."
+            )
+            raise ACMInvalidError(msg)
+
+    delegation_chain: list[str] = (
+        [*parent.delegation_chain, parent.issuer] if parent.delegation_chain else [parent.issuer]
+    )
+
+    child_constraints = constraints if constraints is not None else parent.constraints
+
+    now = datetime.now(UTC)
+    child = _ACMModel(
+        agent=_AgentInfo(spiffe_id=child_spiffe_id),
+        human_sponsor=parent.human_sponsor,
+        capabilities=child_capabilities,
+        constraints=child_constraints,
+        delegation_chain=delegation_chain,
+        issuer=parent.issuer,
+        expires_at=now + timedelta(seconds=ttl),
+        not_before=now,
+    )
+
+    return child

capforge/_exceptions.py

@@ -0,0 +1,21 @@
+"""Custom exception hierarchy for the ACM protocol."""
+
+
+class ACMError(Exception):
+    """Base exception for all ACM-related errors."""
+
+
+class ACMValidationError(ACMError):
+    """Raised when an ACM document fails validation."""
+
+
+class ACMSignatureError(ACMError):
+    """Raised when an ACM document's signature cannot be verified."""
+
+
+class ACMExpiredError(ACMError):
+    """Raised when an ACM document has expired or is not yet valid."""
+
+
+class ACMInvalidError(ACMError):
+    """Raised when an ACM document is structurally invalid."""

capforge/_model.py

@@ -0,0 +1,176 @@
+"""Pydantic data models for the ACM protocol.
+
+This module contains the data models that represent the ACM protocol's
+core data structures. ``Capability`` and ``Constraints`` are public
+classes re-exported from ``capforge``. ``_ACMModel`` is the internal
+Pydantic model used by the ``ACM`` wrapper class.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class Capability(BaseModel):
+    """A single capability granted to an agent.
+
+    ``resource`` and ``action`` together define what the agent is allowed to do.
+    Optional ``constraints`` further scope the capability.
+
+    Example::
+
+        Capability(resource="knowledge_base", action="read")
+        Capability(resource="tickets", action="write",
+                   constraints={"status": "resolved_only"})
+    """
+
+    resource: str = Field(
+        description="Resource type to access (e.g., 'knowledge_base', 'tickets')."
+    )
+    action: str = Field(
+        description="Action to perform on the resource (e.g., 'read', 'write', 'execute')."
+    )
+    constraints: dict[str, str] | None = Field(
+        default=None,
+        description="Optional key-value scoping constraints (e.g., {'status': 'resolved_only'}).",
+    )
+
+
+class Constraints(BaseModel):
+    """Global constraints that apply to all capabilities in a manifest.
+
+    All fields are optional. When a field is ``None``, no constraint is
+    applied for that dimension.
+    """
+
+    max_cost_per_session: float | None = Field(
+        default=None,
+        ge=0,
+        description="Maximum USD cost allowed per session.",
+    )
+    max_tokens_per_session: int | None = Field(
+        default=None,
+        ge=0,
+        description="Maximum tokens allowed per session.",
+    )
+    allowed_models: list[str] | None = Field(
+        default=None,
+        description="If set, only these model names are permitted.",
+    )
+    disallowed_tools: list[str] | None = Field(
+        default=None,
+        description="Tool names that are always forbidden.",
+    )
+    max_execution_seconds: int | None = Field(
+        default=None,
+        ge=0,
+        description="Maximum wall-clock execution time in seconds.",
+    )
+
+
+class _AgentInfo(BaseModel):
+    """Internal model: identifies the AI agent this manifest governs."""
+
+    spiffe_id: str = Field(
+        description="SPIFFE-compatible workload identifier.",
+        pattern=r"^spiffe://",
+    )
+    model: str | None = Field(
+        default=None,
+        description="LLM model name (e.g., 'gpt-5', 'claude-4').",
+    )
+    provider: str | None = Field(
+        default=None,
+        description="Model provider (e.g., 'openai', 'anthropic').",
+    )
+
+
+class _ACMModel(BaseModel):
+    """Internal Pydantic model representing an ACM document.
+
+    This model handles structural validation (SPIFFE patterns, version const,
+    minimum capabilities). Business-logic validation (temporal bounds,
+    delegation chain) is handled by ``_validator``.
+    """
+
+    acm_version: str = Field(
+        default="1.0",
+        description="Protocol version. Must be '1.0' for this revision.",
+    )
+    agent: _AgentInfo = Field(description="The AI agent this manifest applies to.")
+    human_sponsor: str = Field(description="Email or SPIFFE ID of the responsible human or team.")
+    capabilities: list[Capability] = Field(
+        description="Capabilities granted to the agent (at least one required).",
+        min_length=1,
+    )
+    constraints: Constraints | None = Field(
+        default=None,
+        description="Optional global constraints.",
+    )
+    delegation_chain: list[str] | None = Field(
+        default=None,
+        description="Ordered SPIFFE IDs representing the delegation path.",
+    )
+    issuer: str = Field(
+        description="SPIFFE ID of the entity that signed this manifest.",
+        pattern=r"^spiffe://",
+    )
+    expires_at: datetime = Field(description="ISO 8601 UTC expiration timestamp.")
+    not_before: datetime | None = Field(
+        default=None,
+        description="ISO 8601 UTC timestamp before which this is invalid.",
+    )
+    signature: str | None = Field(
+        default=None,
+        description="Base64-encoded Ed25519 signature.",
+    )
+    metadata: dict[str, Any] | None = Field(
+        default=None,
+        description="Extension point for implementation-specific metadata.",
+    )
+
+    @field_validator("acm_version")
+    @classmethod
+    def _validate_version(cls, v: str) -> str:
+        if v != "1.0":
+            msg = f"Unsupported ACM version: {v!r}. Only '1.0' is supported."
+            raise ValueError(msg)
+        return v
+
+    @field_validator("capabilities")
+    @classmethod
+    def _validate_capabilities_not_empty(cls, v: list[Capability]) -> list[Capability]:
+        if not v:
+            msg = "At least one capability is required."
+            raise ValueError(msg)
+        return v
+
+    def is_expired(self, reference_time: datetime | None = None) -> bool:
+        """Return True if the current time is past ``expires_at``."""
+        now = reference_time or datetime.now(UTC)
+        expires = (
+            self.expires_at.replace(tzinfo=UTC)
+            if self.expires_at.tzinfo is None
+            else self.expires_at
+        )
+        ref = now.replace(tzinfo=UTC) if now.tzinfo is None else now
+        return ref > expires
+
+    def is_valid_now(self, reference_time: datetime | None = None) -> bool:
+        """Return True if the document is within its validity window."""
+        now = reference_time or datetime.now(UTC)
+        if self.is_expired(now):
+            return False
+        if self.not_before is not None:
+            ref = now.replace(tzinfo=UTC) if now.tzinfo is None else now
+            nb = (
+                self.not_before.replace(tzinfo=UTC)
+                if self.not_before.tzinfo is None
+                else self.not_before
+            )
+            if ref < nb:
+                return False
+        return True

capforge/_policy.py

@@ -0,0 +1,341 @@
+"""Runtime authorization engine for CapForge.
+
+Transforms CapForge from a static manifest library into a runtime
+authorization engine. The engine answers the question:
+
+    "May this action execute right now?"
+
+Instead of:
+    "Does this capability exist?"
+
+The public interface is ``ACM.check()``. The internal evaluators
+(``RuntimeEvaluator``, ``ConstraintEvaluator``, ``BudgetEvaluator``)
+are implementation details.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from capforge._exceptions import ACMExpiredError
+from capforge._model import Constraints, _ACMModel
+
+# ── Public Types ──────────────────────────────────────────────────
+
+
+@dataclass
+class PolicyDecision:
+    """The result of a runtime authorization check.
+
+    Attributes
+    ----------
+    allowed:
+        Whether the action is authorized.
+    reason:
+        Human-readable explanation of the decision.
+    failed_constraint:
+        Which specific constraint was violated, if any.
+        Example: ``"max_cost_per_session"``, ``"capability"``, ``"expired"``.
+    remaining_budget:
+        If a budget constraint was evaluated, shows remaining capacity.
+        Keys are constraint names (e.g., ``"cost"``, ``"tokens"``).
+    """
+
+    allowed: bool
+    reason: str | None = None
+    failed_constraint: str | None = None
+    remaining_budget: dict[str, float] = field(default_factory=dict)
+
+
+# ── Internal Evaluators ──────────────────────────────────────────
+
+
+class BudgetEvaluator:
+    """Evaluates cost and token budget constraints.
+
+    Does NOT raise exceptions — returns a ``(allowed, remaining, reason)`` tuple.
+    """
+
+    @staticmethod
+    def check_cost(
+        constraints: Constraints | None,
+        cost: float | None,
+        session_cost: float | None,
+    ) -> tuple[bool, dict[str, float], str | None]:
+        """Check that the action's cost + session cost stays within budget.
+
+        Returns (allowed, remaining_budget, failed_constraint_name).
+        """
+        remaining: dict[str, float] = {}
+
+        if constraints is None or constraints.max_cost_per_session is None:
+            return True, remaining, None
+
+        budget = constraints.max_cost_per_session
+
+        # Session cost check
+        if session_cost is not None and session_cost > budget:
+            remaining["cost"] = budget
+            return False, remaining, "max_cost_per_session"
+
+        # Single action cost check
+        if cost is not None and cost > budget:
+            remaining["cost"] = budget
+            return False, remaining, "max_cost_per_session"
+
+        # Both checks pass — compute remaining budget
+        used = (session_cost or 0.0) + (cost or 0.0)
+        remaining["cost"] = max(0.0, budget - used)
+        return True, remaining, None
+
+    @staticmethod
+    def check_tokens(
+        constraints: Constraints | None,
+        session_tokens: int | None,
+    ) -> tuple[bool, dict[str, float], str | None]:
+        """Check that the session token count stays within budget."""
+        remaining: dict[str, float] = {}
+
+        if constraints is None or constraints.max_tokens_per_session is None:
+            return True, remaining, None
+
+        budget = float(constraints.max_tokens_per_session)
+
+        if session_tokens is not None and session_tokens > constraints.max_tokens_per_session:
+            remaining["tokens"] = budget
+            return False, remaining, "max_tokens_per_session"
+
+        remaining["tokens"] = max(0.0, budget - float(session_tokens or 0))
+        return True, remaining, None
+
+
+class ConstraintEvaluator:
+    """Evaluates model, tool, and execution time constraints.
+
+    Does NOT raise exceptions — returns a ``(allowed, reason)`` tuple.
+    """
+
+    @staticmethod
+    def check_model(
+        constraints: Constraints | None,
+        model: str | None,
+    ) -> tuple[bool, str | None]:
+        """Check that *model* is in the allowed_models list (if set)."""
+        if constraints is None or constraints.allowed_models is None:
+            return True, None
+        if model is None:
+            return True, None
+        if model in constraints.allowed_models:
+            return True, None
+        return False, "allowed_models"
+
+    @staticmethod
+    def check_tool(
+        constraints: Constraints | None,
+        tool_name: str | None,
+    ) -> tuple[bool, str | None]:
+        """Check that *tool_name* is not in the disallowed_tools list."""
+        if constraints is None or constraints.disallowed_tools is None:
+            return True, None
+        if tool_name is None:
+            return True, None
+        if tool_name not in constraints.disallowed_tools:
+            return True, None
+        return False, "disallowed_tools"
+
+    @staticmethod
+    def check_execution_time(
+        constraints: Constraints | None,
+        execution_seconds: float | None,
+    ) -> tuple[bool, str | None]:
+        """Check that execution time is within the allowed limit."""
+        if constraints is None or constraints.max_execution_seconds is None:
+            return True, None
+        if execution_seconds is None:
+            return True, None
+        if execution_seconds <= constraints.max_execution_seconds:
+            return True, None
+        return False, "max_execution_seconds"
+
+
+class RuntimeEvaluator:
+    """Main runtime evaluator — orchestrates all checks.
+
+    This is the internal implementation behind ``ACM.check()``.
+    """
+
+    def __init__(self) -> None:
+        self._budget = BudgetEvaluator()
+        self._constraint = ConstraintEvaluator()
+
+    def check(
+        self,
+        acm: _ACMModel,
+        *,
+        resource: str | None = None,
+        action: str | None = None,
+        tool: str | None = None,
+        cost: float | None = None,
+        session_cost: float | None = None,
+        session_tokens: int | None = None,
+        model: str | None = None,
+        execution_seconds: float | None = None,
+    ) -> PolicyDecision:
+        """Evaluate an action against an ACM document at runtime.
+
+        Parameters
+        ----------
+        acm:
+            The ACM document to evaluate.
+        resource:
+            Resource type to check in capabilities.
+        action:
+            Action to check in capabilities.
+        tool:
+            Tool name to check against ``disallowed_tools``.
+        cost:
+            Cost of this single action in USD.
+        session_cost:
+            Total cost so far in the current session in USD.
+        session_tokens:
+            Total tokens so far in the current session.
+        model:
+            Model name to check against ``allowed_models``.
+        execution_seconds:
+            Execution time so far in seconds.
+
+        Returns
+        -------
+        PolicyDecision
+            Structured result with decision, reason, and remaining budget.
+        """
+        remaining_budget: dict[str, float] = {}
+
+        # ── 1. Temporal check ─────────────────────────────────
+        try:
+            self._check_temporal(acm)
+        except ACMExpiredError as e:
+            return PolicyDecision(
+                allowed=False,
+                reason=str(e),
+                failed_constraint="expired",
+            )
+
+        # ── 2. Capability check ───────────────────────────────
+        if resource is not None or action is not None:
+            cap_decision = self._check_capability(acm, resource, action)
+            if not cap_decision.allowed:
+                return cap_decision
+
+        # ── 3. Model constraint ───────────────────────────────
+        model_ok, model_fail = self._constraint.check_model(acm.constraints, model)
+        if not model_ok:
+            return PolicyDecision(
+                allowed=False,
+                reason=f"Model '{model}' is not in allowed_models",
+                failed_constraint=model_fail,
+            )
+
+        # ── 4. Tool constraint ────────────────────────────────
+        tool_ok, tool_fail = self._constraint.check_tool(acm.constraints, tool)
+        if not tool_ok:
+            return PolicyDecision(
+                allowed=False,
+                reason=f"Tool '{tool}' is disallowed",
+                failed_constraint=tool_fail,
+            )
+
+        # ── 5. Execution time constraint ──────────────────────
+        time_ok, time_fail = self._constraint.check_execution_time(
+            acm.constraints, execution_seconds
+        )
+        if not time_ok:
+            return PolicyDecision(
+                allowed=False,
+                reason=f"Execution time {execution_seconds}s exceeds max allowed",
+                failed_constraint=time_fail,
+            )
+
+        # ── 6. Budget checks ──────────────────────────────────
+        budget_ok, budget_remaining, cost_fail = self._budget.check_cost(
+            acm.constraints, cost, session_cost
+        )
+        remaining_budget.update(budget_remaining)
+        if not budget_ok:
+            return PolicyDecision(
+                allowed=False,
+                reason=_budget_fail_reason(cost_fail, cost, session_cost),
+                failed_constraint=cost_fail,
+                remaining_budget=remaining_budget,
+            )
+
+        tokens_ok, tokens_remaining, tokens_fail = self._budget.check_tokens(
+            acm.constraints, session_tokens
+        )
+        remaining_budget.update(tokens_remaining)
+        if not tokens_ok:
+            return PolicyDecision(
+                allowed=False,
+                reason=f"Session token budget exceeded ({session_tokens} tokens used)",
+                failed_constraint=tokens_fail,
+                remaining_budget=remaining_budget,
+            )
+
+        # ── All checks passed ─────────────────────────────────
+        return PolicyDecision(
+            allowed=True,
+            reason="Action authorized",
+            remaining_budget=remaining_budget,
+        )
+
+    def _check_temporal(self, acm: _ACMModel) -> None:
+        """Check temporal validity — raises ACMExpiredError if invalid."""
+        now = datetime.now(UTC)
+        expires = (
+            acm.expires_at.replace(tzinfo=UTC) if acm.expires_at.tzinfo is None else acm.expires_at
+        )
+        if now > expires:
+            raise ACMExpiredError(f"ACM expired at {acm.expires_at}")
+
+        if acm.not_before is not None:
+            nb = (
+                acm.not_before.replace(tzinfo=UTC)
+                if acm.not_before.tzinfo is None
+                else acm.not_before
+            )
+            if now < nb:
+                raise ACMExpiredError(f"ACM is not yet valid until {acm.not_before}")
+
+    def _check_capability(
+        self,
+        acm: _ACMModel,
+        resource: str | None,
+        action: str | None,
+    ) -> PolicyDecision:
+        """Check that the capability exists in the ACM."""
+        if resource is None or action is None:
+            return PolicyDecision(allowed=True)
+
+        for cap in acm.capabilities:
+            if cap.resource == resource and cap.action == action:
+                return PolicyDecision(allowed=True)
+
+        return PolicyDecision(
+            allowed=False,
+            reason=f"Capability '{resource}:{action}' is not authorized",
+            failed_constraint="capability",
+        )
+
+
+def _budget_fail_reason(
+    failed: str | None,
+    cost: float | None,
+    session_cost: float | None,
+) -> str:
+    """Build a human-readable budget failure message."""
+    if failed == "max_cost_per_session":
+        if session_cost is not None and (cost is None or session_cost > (cost or 0)):
+            return f"Session cost {session_cost} exceeds budget"
+        return f"Action cost {cost} exceeds budget"
+    return "Budget constraint exceeded"

capforge/_validator.py

@@ -0,0 +1,71 @@
+"""Validation logic for ACM documents.
+
+The ``_validate`` function validates an ACM document against rules that
+cannot be expressed by the Pydantic model alone:
+
+- Temporal bounds (not expired, not before ``not_before``).
+- Delegation chain invariants (all entries are valid SPIFFE IDs).
+
+Structural validation (SPIFFE ID patterns, version const, minimum capabilities)
+is handled by the Pydantic model.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from capforge._exceptions import ACMExpiredError, ACMValidationError
+from capforge._model import _ACMModel
+
+
+def validate(acm: _ACMModel, reference_time: datetime | None = None) -> None:
+    """Validate an ACM document, raising on any violation.
+
+    Checks performed (Pydantic-level checks excluded — those fire during
+    model construction):
+
+    1. Temporal validity — ``expires_at`` and ``not_before``.
+    2. Delegation chain — every entry is a valid SPIFFE ID.
+
+    Parameters
+    ----------
+    acm:
+        The ACM document to validate.
+    reference_time:
+        Reference time for temporal checks. Defaults to current UTC time.
+
+    Raises
+    ------
+    ACMValidationError
+        If the document fails any validation rule.
+    ACMExpiredError
+        If the document is expired or not yet valid.
+    """
+    errors: list[str] = []
+    has_temporal_error = False
+
+    if acm.delegation_chain:
+        for i, entry in enumerate(acm.delegation_chain):
+            if not entry.startswith("spiffe://"):
+                errors.append(f"Invalid SPIFFE ID in delegation_chain[{i}]: {entry!r}")
+
+    ref = reference_time or datetime.now(UTC)
+    ref_utc = ref.replace(tzinfo=UTC) if ref.tzinfo is None else ref
+
+    expires = (
+        acm.expires_at.replace(tzinfo=UTC) if acm.expires_at.tzinfo is None else acm.expires_at
+    )
+    if ref_utc > expires:
+        errors.append(f"ACM expired at {acm.expires_at} (reference: {ref})")
+        has_temporal_error = True
+
+    if acm.not_before is not None:
+        nb = acm.not_before.replace(tzinfo=UTC) if acm.not_before.tzinfo is None else acm.not_before
+        if ref_utc < nb:
+            errors.append(f"ACM is not yet valid — not_before={acm.not_before} (reference: {ref})")
+            has_temporal_error = True
+
+    if errors:
+        if has_temporal_error:
+            raise ACMExpiredError("; ".join(errors))
+        raise ACMValidationError("; ".join(errors))

capforge/_version.py

@@ -0,0 +1,3 @@
+"""Version information for the capforge package."""
+
+__version__ = "0.1.0"

capforge/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface for CapForge (ACM protocol)."""