capforge 0.4.0__py3-none-any.whl

capforge/__init__.py

@@ -0,0 +1,50 @@
+"""CapForge — Agent Capability Manifest (ACM) SDK.
+
+CapForge is the reference Python implementation of the Agent Capability
+Manifest (ACM) protocol. It provides a clean API for creating, signing,
+verifying, delegating, saving, and loading ACM documents.
+
+Basic usage::
+
+    from capforge import ACM, Capability, Constraints
+
+    # Create a new manifest
+    manifest = ACM.create(
+        spiffe_id="spiffe://org/agent/my-bot",
+        sponsor="user@org.com",
+        capabilities=[Capability(resource="kb", action="read")],
+        constraints=Constraints(max_cost_per_session=0.05),
+    )
+
+    # Sign, save, load, verify
+    manifest.sign("my-key.pem").save("manifest.json")
+    loaded = ACM.load("manifest.json")
+    loaded.verify(trusted_keys=["my-key.pub"])
+"""
+
+from __future__ import annotations
+
+from capforge._acm import ACM
+from capforge._exceptions import (
+    ACMError,
+    ACMExpiredError,
+    ACMInvalidError,
+    ACMSignatureError,
+    ACMValidationError,
+)
+from capforge._model import Capability, Constraints
+from capforge._policy import PolicyDecision
+from capforge._version import __version__
+
+__all__: list[str] = [
+    "ACM",
+    "ACMError",
+    "ACMExpiredError",
+    "ACMInvalidError",
+    "ACMSignatureError",
+    "ACMValidationError",
+    "Capability",
+    "Constraints",
+    "PolicyDecision",
+    "__version__",
+]

capforge/_acm.py

@@ -0,0 +1,491 @@
+"""Main public API for the CapForge SDK.
+
+The ``ACM`` class provides the primary interface for creating, signing,
+verifying, delegating, saving, and loading Agent Capability Manifest
+documents.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+
+from capforge._crypto import (
+    load_private_key,
+    load_public_key,
+    sign_dict,
+    verify_dict,
+)
+from capforge._delegation import delegate as _delegate_model
+from capforge._exceptions import ACMError, ACMSignatureError
+from capforge._model import (
+    Capability,
+    Constraints,
+    _ACMModel,
+    _AgentInfo,
+)
+from capforge._policy import PolicyDecision, RuntimeEvaluator
+from capforge._validator import validate as _validate
+
+
+class ACM:
+    """Agent Capability Manifest — the primary interface for ACM documents.
+
+    Create, sign, verify, delegate, save, and load Agent Capability Manifest
+    documents.
+
+    Basic usage::
+
+        from capforge import ACM, Capability, Constraints
+
+        # Create a new manifest
+        manifest = ACM.create(
+            spiffe_id="spiffe://org/agent/my-bot",
+            sponsor="user@org.com",
+            capabilities=[Capability(resource="kb", action="read")],
+        )
+
+        # Sign and save it
+        manifest.sign("my-key.pem")
+        manifest.save("manifest.json")
+
+        # Load and verify
+        loaded = ACM.load("manifest.json")
+        loaded.verify()
+    """
+
+    def __init__(self, model: _ACMModel) -> None:
+        self._model = model
+
+    # ── Factory Methods ───────────────────────────────────────────
+
+    @classmethod
+    def create(
+        cls,
+        spiffe_id: str,
+        sponsor: str,
+        capabilities: list[Capability],
+        *,
+        issuer: str | None = None,
+        constraints: Constraints | None = None,
+        ttl: int = 3600,
+        not_before: datetime | None = None,
+        metadata: dict[str, Any] | None = None,
+        model: str | None = None,
+        provider: str | None = None,
+    ) -> ACM:
+        """Create a new ACM manifest.
+
+        Parameters
+        ----------
+        spiffe_id:
+            SPIFFE ID of the agent being authorized.
+        sponsor:
+            Email or SPIFFE ID of the responsible human or team.
+        capabilities:
+            List of capabilities to grant.
+        issuer:
+            SPIFFE ID of the issuing entity. Defaults to *spiffe_id*.
+        constraints:
+            Optional global constraints.
+        ttl:
+            Time-to-live in seconds (default 3600 = 1 hour).
+        not_before:
+            Optional ISO 8601 timestamp before which the manifest is invalid.
+        metadata:
+            Optional implementation-specific metadata.
+        model:
+            Optional LLM model name (e.g., ``"gpt-5"``).
+        provider:
+            Optional model provider (e.g., ``"openai"``).
+
+        Returns
+        -------
+        ACM
+            A new unsigned ACM manifest.
+        """
+        now = datetime.now(UTC)
+        acm_model = _ACMModel(
+            agent=_AgentInfo(
+                spiffe_id=spiffe_id,
+                model=model,
+                provider=provider,
+            ),
+            human_sponsor=sponsor,
+            capabilities=capabilities,
+            constraints=constraints,
+            issuer=issuer or spiffe_id,
+            expires_at=now + timedelta(seconds=ttl),
+            not_before=not_before or now,
+            metadata=metadata,
+        )
+        return cls(acm_model)
+
+    @classmethod
+    def load(cls, source: str | Path | dict[str, Any]) -> ACM:
+        """Load an ACM manifest from a JSON file or dictionary.
+
+        Parameters
+        ----------
+        source:
+            Path to a JSON file, or a dictionary representing the ACM.
+
+        Returns
+        -------
+        ACM
+            The loaded manifest.
+        """
+        if isinstance(source, (str, Path)):
+            path = Path(source)
+            with path.open() as f:
+                data = json.load(f)
+        else:
+            data = source
+
+        model = _ACMModel.model_validate(data)
+        return cls(model)
+
+    # ── Persistence ───────────────────────────────────────────────
+
+    def save(self, path: str | Path | None = None) -> str:
+        """Save this manifest to a JSON file and/or return its JSON string.
+
+        Parameters
+        ----------
+        path:
+            Optional file path. If provided, the JSON is written to this file.
+
+        Returns
+        -------
+        str
+            The pretty-printed JSON string of this manifest.
+        """
+        result = self._model.model_dump_json(indent=2)
+        if path is not None:
+            Path(path).write_text(result + "\n")
+        return result
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return this manifest as a dictionary (JSON-safe)."""
+        return self._model.model_dump()
+
+    def to_json(self) -> str:
+        """Return this manifest as a pretty-printed JSON string."""
+        return self._model.model_dump_json(indent=2)
+
+    # ── Signing ───────────────────────────────────────────────────
+
+    def sign(self, key: Ed25519PrivateKey | str | Path) -> ACM:
+        """Sign this manifest with an Ed25519 private key.
+
+        The signature is added to the manifest in-place.
+
+        Parameters
+        ----------
+        key:
+            An ``Ed25519PrivateKey`` instance, or a path to a PEM file.
+
+        Returns
+        -------
+        ACM
+            ``self``, with the signature attached (for chaining).
+        """
+        if isinstance(key, (str, Path)):
+            key = load_private_key(key)
+
+        acm_dict = json.loads(self._model.model_dump_json())
+        self._model.signature = sign_dict(acm_dict, key)
+        return self
+
+    # ── Verification ──────────────────────────────────────────────
+
+    def verify(
+        self,
+        *,
+        trusted_keys: list[str | Path | Ed25519PublicKey] | None = None,
+    ) -> None:
+        """Verify this manifest's temporal validity and optionally its signature.
+
+        Parameters
+        ----------
+        trusted_keys:
+            Optional list of trusted public keys (PEM paths or key instances)
+            to verify the signature against. If provided, signature verification
+            is performed against each key until one succeeds.
+
+        Raises
+        ------
+        ACMExpiredError
+            If the manifest has expired or is not yet valid.
+        ACMValidationError
+            If the manifest fails structural or delegation chain validation.
+        ACMSignatureError
+            If the signature is missing, invalid, or cannot be verified.
+        """
+        _validate(self._model)
+
+        if trusted_keys is not None:
+            if self._model.signature is None:
+                raise ACMSignatureError("Cannot verify signature: no signature in manifest.")
+            self._verify_signature(trusted_keys)
+
+    def _verify_signature(
+        self,
+        trusted_keys: list[str | Path | Ed25519PublicKey],
+    ) -> None:
+        """Verify the signature against one or more trusted keys."""
+        acm_dict = json.loads(self._model.model_dump_json())
+        signature = self._model.signature
+        if signature is None:
+            raise ACMSignatureError("No signature to verify")
+
+        errors: list[str] = []
+        for key_source in trusted_keys:
+            try:
+                if isinstance(key_source, (str, Path)):
+                    pub_key = load_public_key(key_source)
+                else:
+                    pub_key = key_source
+
+                if verify_dict(acm_dict, signature, pub_key):
+                    return
+            except ACMError as e:
+                name = str(key_source) if isinstance(key_source, (str, Path)) else "provided key"
+                errors.append(f"{name}: {e}")
+
+        if errors:
+            details = "; ".join(errors)
+            raise ACMSignatureError(
+                f"Signature could not be verified against any trusted key: {details}"
+            )
+
+    # ── Delegation ────────────────────────────────────────────────
+
+    def delegate(
+        self,
+        child_spiffe_id: str,
+        capabilities: list[Capability],
+        *,
+        ttl: int = 3600,
+        key: Ed25519PrivateKey | str | Path | None = None,
+    ) -> ACM:
+        """Create a delegated ACM with narrowed scope.
+
+        Parameters
+        ----------
+        child_spiffe_id:
+            SPIFFE ID of the child agent.
+        capabilities:
+            Capabilities to delegate. Must be a subset of the parent's.
+        ttl:
+            Time-to-live in seconds for the delegated ACM.
+        key:
+            Optional private key to sign the delegated manifest.
+
+        Returns
+        -------
+        ACM
+            A new ACM instance representing the delegated manifest.
+        """
+        child_model = _delegate_model(
+            parent=self._model,
+            child_spiffe_id=child_spiffe_id,
+            child_capabilities=capabilities,
+            ttl=ttl,
+        )
+        child = ACM(child_model)
+
+        if key is not None:
+            child.sign(key)
+
+        return child
+
+    # ── Runtime Authorization Check ──────────────────────────────
+
+    def check(
+        self,
+        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 whether an action is authorized right now.
+
+        This is the runtime authorization engine — it checks temporal
+        validity, capability presence, and all constraints (budget,
+        models, tools, execution time) in a single call.
+
+        Parameters
+        ----------
+        resource:
+            Resource type to check (e.g., ``"knowledge_base"``).
+        action:
+            Action to check (e.g., ``"read"``).
+        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
+            A structured decision with ``allowed``, ``reason``,
+            ``failed_constraint``, and ``remaining_budget``.
+
+        Example::
+
+            result = manifest.check(
+                resource="github",
+                action="search",
+                cost=0.02,
+                session_cost=0.20,
+                session_tokens=1000,
+                tool="github.search",
+                model="gpt-5",
+            )
+            if result.allowed:
+                print(f"Allowed — remaining budget: {result.remaining_budget}")
+            else:
+                print(f"Denied: {result.reason} ({result.failed_constraint})")
+        """
+        evaluator = RuntimeEvaluator()
+        return evaluator.check(
+            self._model,
+            resource=resource,
+            action=action,
+            tool=tool,
+            cost=cost,
+            session_cost=session_cost,
+            session_tokens=session_tokens,
+            model=model,
+            execution_seconds=execution_seconds,
+        )
+
+    # ── Capability Lookup ─────────────────────────────────────────
+
+    def has_capability(self, resource: str, action: str) -> bool:
+        """Check if a specific capability is present in this manifest.
+
+        Parameters
+        ----------
+        resource:
+            The resource type to check.
+        action:
+            The action to check.
+
+        Returns
+        -------
+        bool
+            True if the capability exists in this manifest.
+        """
+        return any(c.resource == resource and c.action == action for c in self._model.capabilities)
+
+    def get_capability(self, resource: str, action: str) -> Capability | None:
+        """Get a specific capability by resource and action.
+
+        Returns the ``Capability`` if found, or ``None``.
+        """
+        for c in self._model.capabilities:
+            if c.resource == resource and c.action == action:
+                return c
+        return None
+
+    # ── Temporal Checks ───────────────────────────────────────────
+
+    def is_valid(self) -> bool:
+        """Return True if this manifest is within its temporal validity window."""
+        return self._model.is_valid_now()
+
+    def is_expired(self) -> bool:
+        """Return True if this manifest has expired."""
+        return self._model.is_expired()
+
+    # ── Properties ────────────────────────────────────────────────
+
+    @property
+    def spiffe_id(self) -> str:
+        """The SPIFFE ID of the agent this manifest authorizes."""
+        return self._model.agent.spiffe_id
+
+    @property
+    def capabilities_list(self) -> list[Capability]:
+        """The list of capabilities in this manifest."""
+        return list(self._model.capabilities)
+
+    @property
+    def constraints_obj(self) -> Constraints | None:
+        """The global constraints on this manifest, or None."""
+        return self._model.constraints
+
+    @property
+    def sponsor(self) -> str:
+        """The human sponsor of this manifest."""
+        return self._model.human_sponsor
+
+    @property
+    def issuer(self) -> str:
+        """The SPIFFE ID of the signing entity."""
+        return self._model.issuer
+
+    @property
+    def expires_at(self) -> datetime:
+        """The expiration timestamp."""
+        return self._model.expires_at
+
+    @property
+    def not_before(self) -> datetime | None:
+        """The not-before timestamp, or None."""
+        return self._model.not_before
+
+    @property
+    def delegation_chain(self) -> list[str] | None:
+        """The delegation chain, or None if this is a root manifest."""
+        return self._model.delegation_chain
+
+    @property
+    def signature(self) -> str | None:
+        """The base64-encoded signature, or None if unsigned."""
+        return self._model.signature
+
+    @property
+    def metadata(self) -> dict[str, Any] | None:
+        """Implementation-specific metadata, or None."""
+        return self._model.metadata
+
+    @property
+    def acm_version(self) -> str:
+        """The ACM protocol version."""
+        return self._model.acm_version
+
+    @property
+    def agent_model(self) -> str | None:
+        """The LLM model name, or None."""
+        return self._model.agent.model
+
+    @property
+    def agent_provider(self) -> str | None:
+        """The model provider, or None."""
+        return self._model.agent.provider
+
+    def __repr__(self) -> str:
+        status = "valid" if self.is_valid() else "expired"
+        caps = len(self._model.capabilities)
+        sig = "signed" if self._model.signature else "unsigned"
+        return f"ACM(spiffe_id={self.spiffe_id!r}, capabilities={caps}, status={status}, {sig})"

capforge/_crypto.py

@@ -0,0 +1,149 @@
+"""Cryptographic signing and verification for ACM documents.
+
+Uses Ed25519 signatures with canonical JSON serialization.
+The canonical form is: JSON with sorted keys, no whitespace, no signature field.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import Path
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+from cryptography.hazmat.primitives.serialization import (
+    Encoding,
+    NoEncryption,
+    PrivateFormat,
+    PublicFormat,
+    load_pem_private_key,
+    load_pem_public_key,
+)
+
+from capforge._exceptions import ACMSignatureError
+
+
+def generate_private_key() -> Ed25519PrivateKey:
+    """Generate a new Ed25519 private key."""
+    return Ed25519PrivateKey.generate()
+
+
+def private_key_to_bytes(key: Ed25519PrivateKey) -> bytes:
+    """Serialize a private key to PKCS#8 PEM bytes."""
+    return key.private_bytes(
+        encoding=Encoding.PEM,
+        format=PrivateFormat.PKCS8,
+        encryption_algorithm=NoEncryption(),
+    )
+
+
+def public_key_to_bytes(key: Ed25519PrivateKey | Ed25519PublicKey) -> bytes:
+    """Serialize a public key to SubjectPublicKeyInfo PEM bytes."""
+    pub = key.public_key() if isinstance(key, Ed25519PrivateKey) else key
+    return pub.public_bytes(
+        encoding=Encoding.PEM,
+        format=PublicFormat.SubjectPublicKeyInfo,
+    )
+
+
+def load_private_key(path: str | Path) -> Ed25519PrivateKey:
+    """Load an Ed25519 private key from a PEM file."""
+    data = Path(path).read_bytes()
+    key = load_pem_private_key(data, password=None)
+    if not isinstance(key, Ed25519PrivateKey):
+        msg = f"Expected Ed25519 private key, got {type(key).__name__}"
+        raise TypeError(msg)
+    return key
+
+
+def load_public_key(path: str | Path) -> Ed25519PublicKey:
+    """Load an Ed25519 public key from a PEM file."""
+    data = Path(path).read_bytes()
+    key = load_pem_public_key(data)
+    if not isinstance(key, Ed25519PublicKey):
+        msg = f"Expected Ed25519 public key, got {type(key).__name__}"
+        raise TypeError(msg)
+    return key
+
+
+def canonical_json(acm_dict: dict[str, object]) -> bytes:
+    """Serialize an ACM document to canonical JSON bytes.
+
+    The canonical form:
+    - Removes the ``signature`` field (if present).
+    - Sorts all keys lexicographically.
+    - Compact encoding (no whitespace).
+    - No trailing newline.
+    """
+    payload = {k: v for k, v in acm_dict.items() if k != "signature"}
+    return json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+def sign(canonical_bytes: bytes, private_key: Ed25519PrivateKey) -> str:
+    """Sign canonical ACM bytes and return a base64-encoded signature."""
+    sig = private_key.sign(canonical_bytes)
+    return base64.b64encode(sig).decode("ascii")
+
+
+def verify(canonical_bytes: bytes, signature: str, public_key: Ed25519PublicKey) -> bool:
+    """Verify an ACM signature against canonical bytes.
+
+    Returns True if valid.
+    Raises ACMSignatureError if the signature is invalid.
+    """
+    try:
+        sig_bytes = base64.b64decode(signature)
+        public_key.verify(sig_bytes, canonical_bytes)
+        return True
+    except Exception as exc:
+        raise ACMSignatureError(f"Signature verification failed: {exc}") from exc
+
+
+def sign_dict(acm_dict: dict[str, object], private_key: Ed25519PrivateKey) -> str:
+    """Canonicalize an ACM dict and sign it, returning the base64 signature."""
+    canon = canonical_json(acm_dict)
+    return sign(canon, private_key)
+
+
+def verify_dict(
+    acm_dict: dict[str, object],
+    signature: str,
+    public_key: Ed25519PublicKey,
+) -> bool:
+    """Canonicalize an ACM dict and verify its signature."""
+    canon = canonical_json(acm_dict)
+    return verify(canon, signature, public_key)
+
+
+def write_key_pair(
+    private_key: Ed25519PrivateKey,
+    public_key: Ed25519PublicKey | None = None,
+    path_prefix: str = "capforge-key",
+) -> tuple[str, str]:
+    """Write a key pair to PEM files.
+
+    Parameters
+    ----------
+    private_key:
+        The private key to write.
+    public_key:
+        The public key to write. If None, it is derived from the private key.
+    path_prefix:
+        Path prefix for the output files. ``{prefix}.pem`` (private)
+        and ``{prefix}.pub`` (public) will be created.
+
+    Returns
+    -------
+    tuple[str, str]
+        (private_key_path, public_key_path)
+    """
+    priv_path = f"{path_prefix}.pem"
+    Path(priv_path).write_bytes(private_key_to_bytes(private_key))
+
+    if public_key is None:
+        public_key = private_key.public_key()
+
+    pub_path = f"{path_prefix}.pub"
+    Path(pub_path).write_bytes(public_key_to_bytes(public_key))
+
+    return priv_path, pub_path