capforge 0.4.0__tar.gz

capforge-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]" -e capforge_langgraph/
+
+      - name: Lint with ruff
+        run: ruff check .
+
+      - name: Type-check with mypy
+        run: mypy capforge/
+
+      - name: Test with pytest
+        run: pytest

capforge-0.4.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Testing
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.venv/
+venv/

capforge-0.4.0/ARCHITECTURE.md

@@ -0,0 +1,411 @@
+# Architecture
+
+**CapForge — Agent Capability Manifest (ACM) SDK**
+
+This document describes the architecture, module design, data flow, and
+design principles of the CapForge SDK. It is a living document that evolves
+with each phase.
+
+---
+
+## Table of Contents
+
+1. [Design Principles](#1-design-principles)
+2. [Package Structure](#2-package-structure)
+3. [Module Responsibilities](#3-module-responsibilities)
+4. [Public API](#4-public-api)
+5. [Data Flow](#5-data-flow)
+6. [Design Decisions](#6-design-decisions)
+
+---
+
+## 1. Design Principles
+
+### 1.1 Clean Public API
+
+The SDK exposes a minimal, intuitive API. Users should be able to write:
+
+```python
+from capforge import ACM, Capability, Constraints
+
+manifest = ACM.create(...)
+manifest.sign(key).save(path)
+loaded = ACM.load(path)
+loaded.verify(trusted_keys=...)
+```
+
+Internal implementation details are hidden behind `_`-prefixed modules.
+
+### 1.2 Protocol, Not Platform
+
+ACM is a document format and signing protocol, not a runtime platform.
+
+**CapForge does not define:**
+- How agents execute (LangGraph, CrewAI handle this)
+- How policies are evaluated (OPA handles this)
+- How audit records are stored (OTel handles this)
+- How identities are issued (SPIFFE handles this)
+
+**CapForge defines:**
+- A signed JSON document format (the ACM)
+- A canonical JSON algorithm for deterministic signing
+- A capability expression model (resource:action pairs)
+- A delegation model with scope narrowing
+- A trust model with root keys and chain of custody
+
+### 1.3 Extensibility Through Metadata
+
+The `metadata` field on ACM documents supports implementation-specific
+annotations, framework-specific configuration, compliance labels, and version
+tags.
+
+### 1.4 Zero Framework Dependency
+
+The CapForge core has **zero dependencies** on any AI framework. Framework
+adapters (LangGraph, CrewAI, etc.) are separate packages.
+
+---
+
+## 2. Package Structure
+
+```
+capforge/                          # Package root
+├── __init__.py                    # Public API — ACM, Capability, Constraints
+├── _version.py                    # Package version (private)
+├── _exceptions.py                 # Exception hierarchy (private)
+├── _model.py                      # Pydantic data models (private)
+│   # Public classes:  Capability, Constraints
+│   # Internal classes: _ACMModel, _AgentInfo
+├── _crypto.py                     # Ed25519 signing/verification (private)
+├── _validator.py                  # Temporal + delegation validation (private)
+├── _delegation.py                 # Delegation scope narrowing (private)
+├── _acm.py                        # Main ACM class (private module, public class)
+├── py.typed                       # PEP 561 type marker
+└── cli/
+    ├── __init__.py
+    └── main.py                    # Click CLI (6 commands)
+
+tests/                             # Test suite
+├── test_acm.py                    # 30 tests for the ACM class
+├── test_crypto.py                 # 14 tests for crypto functions
+├── test_validator.py              # 5 tests for validation logic
+└── test_model.py                  # 7 tests for Capability/Constraints models
+
+spec/                              # Protocol specification
+├── acm-schema.json                # JSON Schema (Draft 2020-12)
+└── examples/
+    ├── valid-acm.json
+    ├── minimal-acm.json
+    └── expired-acm.json
+```
+
+### Naming Convention
+
+- **Public modules:** `capforge/__init__.py` (re-exports the public API)
+- **Private modules:** All modules prefixed with `_` (e.g., `_acm.py`, `_model.py`)
+- **Public classes:** `ACM`, `Capability`, `Constraints` (exported from `__init__.py`)
+- **Internal classes:** Prefixed with `_` (e.g., `_ACMModel`, `_AgentInfo`)
+
+---
+
+## 3. Module Responsibilities
+
+### `capforge/_exceptions.py`
+
+Exception hierarchy — all inheriting from `ACMError`:
+
+```
+ACMError
+├── ACMValidationError     — Schema or business rule violation
+├── ACMSignatureError      — Signature verification failure
+├── ACMExpiredError        — Document expired or not yet valid
+└── ACMInvalidError        — Structurally invalid document
+```
+
+### `capforge/_model.py`
+
+Pydantic models mirroring the ACM JSON Schema:
+
+| Class | Visibility | Description |
+|:------|:-----------|:------------|
+| `Capability` | **Public** | Resource:action pair with optional constraints |
+| `Constraints` | **Public** | Global limits (cost, tokens, models, tools, time) |
+| `_AgentInfo` | Private | Agent identity (SPIFFE + model + provider) |
+| `_ACMModel` | Private | Internal ACM document model with validation |
+
+`_ACMModel` provides:
+- Structural validation (SPIFFE patterns, version const, minimum capabilities)
+- `is_expired()` and `is_valid_now()` temporal checks
+
+### `capforge/_crypto.py`
+
+Ed25519 cryptographic operations:
+
+| Function | Purpose |
+|:---------|:--------|
+| `generate_private_key()` | Create a new Ed25519 key pair |
+| `canonical_json(acm_dict)` | Deterministic JSON for signing |
+| `sign(canonical_bytes, key)` | Return base64 signature |
+| `verify(canonical_bytes, sig, key)` | Verify signature |
+| `sign_dict(acm_dict, key)` | Canonicalize + sign |
+| `verify_dict(acm_dict, sig, key)` | Canonicalize + verify |
+| `load_private_key(path)` | Load PEM private key |
+| `load_public_key(path)` | Load PEM public key |
+| `write_key_pair(key, ...)` | Save PEM key pair to files |
+
+### `capforge/_validator.py`
+
+Business-logic validation that Pydantic cannot express:
+
+- Temporal bounds (`expires_at`, `not_before`)
+- Delegation chain SPIFFE ID validity
+
+Exposes a single function: `validate(acm: _ACMModel, ...) -> None`.
+
+### `capforge/_delegation.py`
+
+Delegation scope narrowing logic:
+
+- Validates child capabilities are a subset of parent capabilities
+- Builds delegation chain (parent chain + parent issuer)
+- Returns a new `_ACMModel` for the delegated document
+
+### `capforge/_policy.py` (Phase 4)
+
+Runtime authorization engine. Turns "does this capability exist?" into
+"may this action execute right now?":
+
+| Component | Role |
+|:----------|:-----|
+| `RuntimeEvaluator` | Orchestrates all checks in order: temporal → capability → model → tool → execution time → cost → tokens |
+| `BudgetEvaluator` | Evaluates cost and token limits against session budgets |
+| `ConstraintEvaluator` | Evaluates model restrictions, disallowed tools, execution timeouts |
+| `PolicyDecision` | Public dataclass with `allowed`, `reason`, `failed_constraint`, `remaining_budget` |
+
+All evaluators are private. The only public interface is `ACM.check()`.
+
+### `capforge/_acm.py`
+
+The main `ACM` class — the public interface for all SDK operations:
+
+| Method | Description |
+|:-------|:------------|
+| `ACM.create(...)` | Factory: create a new manifest |
+| `ACM.load(source)` | Factory: load from file or dict |
+| `manifest.save(path)` | Save to file (returns JSON string) |
+| `manifest.sign(key)` | Sign with Ed25519 key |
+| `manifest.verify(...)` | Temporal + optional crypto verification |
+| `manifest.delegate(...)` | Create delegated ACM |
+| `manifest.has_capability(...)` | Check capability presence |
+| `manifest.get_capability(...)` | Get capability by resource/action |
+| `manifest.is_valid()` | Temporal validity check |
+| `manifest.is_expired()` | Expiry check |
+| `manifest.to_dict()` | Export as dictionary |
+| `manifest.to_json()` | Export as JSON string |
+
+Property accessors: `spiffe_id`, `capabilities_list`, `constraints_obj`,
+`sponsor`, `issuer`, `expires_at`, `not_before`, `delegation_chain`,
+`signature`, `metadata`, `acm_version`, `agent_model`, `agent_provider`.
+
+### `capforge/cli/main.py`
+
+Click-based CLI with 6 commands:
+
+| Command | Purpose |
+|:--------|:---------|
+| `capforge keygen` | Generate Ed25519 key pair |
+| `capforge create` | Create (and optionally sign) an ACM document |
+| `capforge verify` | Verify an ACM document (temporal + optional crypto) |
+| `capforge validate` | Temporal + structural validation only |
+| `capforge info` | Display human-readable ACM information |
+| `capforge delegate` | Create a delegated ACM with narrowed scope |
+
+### `capforge_langgraph/_tool_wrapper.py` (Phase 3b)
+
+ACM-controlled LangGraph tool wrapper:
+
+| Class / Function | Description |
+|:-----------------|:------------|
+| `ACMControlledTool` | Wraps a LangChain ``BaseTool`` with ACM authorization checks |
+| `wrap_tools()` | Convenience to wrap multiple tools with matching capabilities |
+
+`ACMControlledTool` overrides `invoke()`/`ainvoke()` to:
+1. Check ACM temporal validity (`is_valid()`)
+2. Check capability presence (`has_capability(resource, action)`)
+3. Delegates to the inner tool if both checks pass
+
+The adapter uses **only the public CapForge API** (`capforge.ACM`,
+`capforge.Capability`). No private internal modules are imported.
+
+---
+
+## 4. Public API
+
+### Import Paths
+
+```python
+from capforge import ACM          # Main class
+from capforge import Capability   # Capability data model
+from capforge import Constraints  # Constraints data model
+from capforge import __version__  # Package version
+```
+
+### User-Facing API Pattern
+
+```python
+# Create
+manifest = ACM.create(
+    spiffe_id="spiffe://org/agent/bot",
+    sponsor="user@org.com",
+    capabilities=[Capability(resource="kb", action="read")],
+    constraints=Constraints(max_cost_per_session=0.05),
+    ttl=3600,           # optional, default 3600
+    model="gpt-5",      # optional
+    provider="openai",  # optional
+)
+
+# Sign
+manifest.sign("my-key.pem")  # or pass Ed25519PrivateKey object
+
+# Save
+manifest.save("manifest.json")
+
+# Load
+loaded = ACM.load("manifest.json")
+
+# Verify
+loaded.verify()                                # temporal only
+loaded.verify(trusted_keys=["root.pub"])        # temporal + crypto
+
+# Delegate
+child = loaded.delegate(
+    child_spiffe_id="spiffe://org/agent/sub",
+    capabilities=[Capability(resource="kb", action="read")],
+    key="parent-key.pem",  # optional
+)
+```
+
+### Error Handling
+
+All CapForge-specific exceptions inherit from `ACMError`:
+
+```python
+from capforge import ACMError
+from capforge._exceptions import ACMExpiredError, ACMSignatureError
+
+try:
+    manifest.verify(trusted_keys=["root.pub"])
+except ACMExpiredError:
+    print("Manifest has expired")
+except ACMSignatureError:
+    print("Signature verification failed")
+except ACMError:
+    print("Other ACM error")
+```
+
+---
+
+## 5. Data Flow
+
+### ACM Creation Flow
+
+```
+User code or CLI
+    │
+    ├── Provides: SPIFFE ID, sponsor, capabilities, constraints
+    │
+    ▼
+ACM.create()
+    │
+    ├── Constructs _ACMModel (Pydantic validates)
+    │   └── Validates: version="1.0", SPIFFE patterns, min 1 capability
+    │
+    ▼
+ACM instance (wraps _ACMModel)
+    │
+    ├── manifest.sign(key)
+    │   ├── Canonicalizes JSON (sorted keys, no whitespace, no signature)
+    │   ├── Signs with Ed25519
+    │   └── Stores base64 signature in model
+    │
+    ├── manifest.save(path)
+    │   └── Writes pretty-printed JSON to file
+    │
+    ▼
+ACM Document (JSON file or dict)
+```
+
+### ACM Verification Flow
+
+```
+ACM Document (JSON or dict)
+    │
+    ▼
+ACM.load(source)
+    │
+    ├── Parses JSON
+    ├── Constructs _ACMModel (Pydantic structural validation)
+    │
+    ▼
+ACM instance
+    │
+    ├── manifest.verify()
+    │   │
+    │   ├── _validator.validate(_ACMModel)
+    │   │   ├── Temporal check (expires_at, not_before)
+    │   │   └── Delegation chain SPIFFE check
+    │   │
+    │   ├── [If trusted_keys provided]
+    │   │   ├── Re-canonicalize JSON
+    │   │   ├── Verify signature against each trusted key
+    │   │   └── Raise ACMSignatureError if none match
+    │   │
+    │   ▼
+    │   Pass / Raise
+    │
+    ▼
+    Returns None (raises on failure)
+```
+
+### Delegation Flow
+
+```
+Parent ACM (signed)
+    │
+    ▼
+ACM.delegate(child_spiffe_id, capabilities, ...)
+    │
+    ├── Validate child capabilities ⊆ parent capabilities
+    ├── Build delegation chain (parent chain + parent issuer)
+    ├── Create child _ACMModel with narrowed scope
+    ├── [If key provided] Sign child
+    │
+    ▼
+Child ACM (delegated, scoped, optionally signed)
+```
+
+---
+
+## 6. Design Decisions
+
+See [DECISIONS.md](DECISIONS.md) for all 13 Architecture Decision Records.
+
+| ADR | Title | Phase |
+|:----|:------|:------|
+| 001 | SPIFFE ID Format | 1 |
+| 002 | Pydantic for Data Modeling | 1 |
+| 003 | Resource:Action Capability Expression | 1 |
+| 004 | Ed25519 for Signing | 2 |
+| 005 | Separate Validator from Models | 1 |
+| 006 | Manual CLI → Click Migration | 2 |
+| 007 | Optional Metadata Field | 1 |
+| 008 | Canonical JSON Format | 2 |
+| 009 | Type-Narrowed Key Loading | 2 |
+| 010 | PEM-Only Key Format | 2 |
+| 011 | Adapter Interface as Protocol Classes | 3 |
+| 012 | Python Entry Points for Plugin Discovery | 3 |
+| 013 | Zero Core Dependency on AI Frameworks | 3 |
+
+---
+
+*This document was last updated for Phase 3a (CapForge SDK, 2026-07-22).*