aigp-server 0.1.0__tar.gz

aigp_server-0.1.0/.gitignore

@@ -0,0 +1,94 @@
+# Kiro spec/session artifacts — local only
+.kiro/
+
+# ---------------------------------------------------------------------------
+# Python
+# ---------------------------------------------------------------------------
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Packaging / build artifacts
+build/
+dist/
+*.egg-info/
+*.egg
+*.whl
+*.tar.gz
+pip-wheel-metadata/
+
+# Test / tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+
+# ---------------------------------------------------------------------------
+# Node / TypeScript
+# ---------------------------------------------------------------------------
+node_modules/
+clients/typescript/dist/
+*.tsbuildinfo
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# ---------------------------------------------------------------------------
+# Other language build outputs
+# ---------------------------------------------------------------------------
+# Java / Maven
+clients/java/target/
+
+# Rust
+clients/rust/target/
+Cargo.lock
+
+# Go
+clients/go/vendor/
+
+# .NET / C#
+clients/csharp/bin/
+clients/csharp/obj/
+
+# Ruby
+clients/ruby/pkg/
+*.gem
+
+# Swift
+.build/
+Packages/
+*.xcodeproj/
+
+# ---------------------------------------------------------------------------
+# Editor / OS
+# ---------------------------------------------------------------------------
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# ---------------------------------------------------------------------------
+# Secrets / local config
+# ---------------------------------------------------------------------------
+.env
+.env.*
+!.env.example
+*.pem
+*.key

aigp_server-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: aigp-server
+Version: 0.1.0
+Summary: AIGP Governance Server — agentic governance engine (scope envelopes, circuit breakers, delegation)
+Project-URL: Homepage, https://github.com/owner-spec/aigp-protocol
+Project-URL: Repository, https://github.com/owner-spec/aigp-protocol
+Author-email: Evan Erwee <evan@erwee.com>
+License: Proprietary
+Keywords: agentic,ai,aigp,circuit-breaker,governance,protocol,scope-envelope
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# aigp-server — AIGP Governance Engine
+
+Server-side governance engine for the AI Governance Protocol (AIGP). Evaluates agentic governance decisions: tool authorization, plan approval, delegation with scope narrowing, circuit breakers, and memory governance.
+
+## Install
+
+```bash
+pip install aigp-server
+```
+
+## Usage
+
+```python
+from aigp_server import (
+    GovernanceEngine, GovernanceStore, AigpRouter,
+    ScopeEnvelopeManager, CircuitBreakerService,
+)
+
+# 1. Implement the storage interface for your DB
+class MyStore(GovernanceStore):
+    async def put_scope_envelope(self, envelope: dict) -> None: ...
+    async def get_active_scope(self, agent_id: str) -> dict | None: ...
+    # ... (see store.py for full interface)
+
+# 2. Wire up the engine
+store = MyStore()
+scope_mgr = ScopeEnvelopeManager(store)
+cb = CircuitBreakerService(store)
+engine = GovernanceEngine(store, scope_mgr, cb, mode="ENFORCE")
+
+# 3. Create the router (framework-agnostic)
+router = AigpRouter(engine, hmac_secret="your-secret")
+
+# 4. Handle requests — returns (status_code, response_dict)
+status, response = await router.handle_tool_request(headers_dict, body_bytes)
+status, response = await router.handle_plan_submit(headers_dict, body_bytes)
+status, response = await router.handle_escalate(headers_dict, body_bytes)
+status, response = await router.handle_delegate(headers_dict, body_bytes)
+status, response = await router.handle_memory_write(headers_dict, body_bytes)
+```
+
+## Architecture
+
+```
+aigp-server/
+  store.py             — GovernanceStore ABC (implement for your DB)
+  governance_engine.py — Core decision engine (6 handlers)
+  scope_manager.py     — Scope envelope lifecycle + SoD + templates
+  circuit_breaker.py   — 3-state machine with cascading halt
+  routes.py            — Framework-agnostic router (HMAC + dispatch)
+  hmac_auth.py         — HMAC-SHA256 verify/sign utilities
+```
+
+## Handlers
+
+| Handler | RFC §15 | Decision |
+|---------|---------|----------|
+| `handle_tool_request` | §15.6 | ALLOW / DENY (scope + budget + circuit breaker) |
+| `handle_plan_submit` | §15.8 | APPROVED / APPROVED_WITH_MODIFICATIONS / REJECTED |
+| `handle_step_complete` | — | Budget decrement + circuit breaker outcome |
+| `handle_escalate` | §15.9 | Creates pending task for human review |
+| `handle_delegate` | §15.10 | Scope narrowing (A ∩ B), depth limit (max 5) |
+| `handle_memory_write` | §15.13 | Classification + retention + isolation check |
+
+## Modes
+
+| Mode | Behavior |
+|------|----------|
+| `REPORT` | Log denials but return ALLOW (shadow mode) |
+| `REPORT-TRACE` | Same as REPORT + emit trace telemetry |
+| `ENFORCE` | Deny violations (fail-closed) |
+
+## License
+
+Proprietary — © 2025-2026 Evan Erwee. All rights reserved.

aigp_server-0.1.0/README.md

@@ -0,0 +1,75 @@
+# aigp-server — AIGP Governance Engine
+
+Server-side governance engine for the AI Governance Protocol (AIGP). Evaluates agentic governance decisions: tool authorization, plan approval, delegation with scope narrowing, circuit breakers, and memory governance.
+
+## Install
+
+```bash
+pip install aigp-server
+```
+
+## Usage
+
+```python
+from aigp_server import (
+    GovernanceEngine, GovernanceStore, AigpRouter,
+    ScopeEnvelopeManager, CircuitBreakerService,
+)
+
+# 1. Implement the storage interface for your DB
+class MyStore(GovernanceStore):
+    async def put_scope_envelope(self, envelope: dict) -> None: ...
+    async def get_active_scope(self, agent_id: str) -> dict | None: ...
+    # ... (see store.py for full interface)
+
+# 2. Wire up the engine
+store = MyStore()
+scope_mgr = ScopeEnvelopeManager(store)
+cb = CircuitBreakerService(store)
+engine = GovernanceEngine(store, scope_mgr, cb, mode="ENFORCE")
+
+# 3. Create the router (framework-agnostic)
+router = AigpRouter(engine, hmac_secret="your-secret")
+
+# 4. Handle requests — returns (status_code, response_dict)
+status, response = await router.handle_tool_request(headers_dict, body_bytes)
+status, response = await router.handle_plan_submit(headers_dict, body_bytes)
+status, response = await router.handle_escalate(headers_dict, body_bytes)
+status, response = await router.handle_delegate(headers_dict, body_bytes)
+status, response = await router.handle_memory_write(headers_dict, body_bytes)
+```
+
+## Architecture
+
+```
+aigp-server/
+  store.py             — GovernanceStore ABC (implement for your DB)
+  governance_engine.py — Core decision engine (6 handlers)
+  scope_manager.py     — Scope envelope lifecycle + SoD + templates
+  circuit_breaker.py   — 3-state machine with cascading halt
+  routes.py            — Framework-agnostic router (HMAC + dispatch)
+  hmac_auth.py         — HMAC-SHA256 verify/sign utilities
+```
+
+## Handlers
+
+| Handler | RFC §15 | Decision |
+|---------|---------|----------|
+| `handle_tool_request` | §15.6 | ALLOW / DENY (scope + budget + circuit breaker) |
+| `handle_plan_submit` | §15.8 | APPROVED / APPROVED_WITH_MODIFICATIONS / REJECTED |
+| `handle_step_complete` | — | Budget decrement + circuit breaker outcome |
+| `handle_escalate` | §15.9 | Creates pending task for human review |
+| `handle_delegate` | §15.10 | Scope narrowing (A ∩ B), depth limit (max 5) |
+| `handle_memory_write` | §15.13 | Classification + retention + isolation check |
+
+## Modes
+
+| Mode | Behavior |
+|------|----------|
+| `REPORT` | Log denials but return ALLOW (shadow mode) |
+| `REPORT-TRACE` | Same as REPORT + emit trace telemetry |
+| `ENFORCE` | Deny violations (fail-closed) |
+
+## License
+
+Proprietary — © 2025-2026 Evan Erwee. All rights reserved.

aigp_server-0.1.0/aigp_server/__init__.py

@@ -0,0 +1,38 @@
+"""AIGP Server — Agentic Governance Engine package.
+
+Usage:
+    from aigp_server import GovernanceEngine, GovernanceStore, AigpRouter
+
+    # Implement GovernanceStore for your DB:
+    class MyStore(GovernanceStore): ...
+
+    # Wire up:
+    store = MyStore()
+    scope_mgr = ScopeEnvelopeManager(store)
+    cb = CircuitBreakerService(store)
+    engine = GovernanceEngine(store, scope_mgr, cb, mode="ENFORCE")
+    router = AigpRouter(engine, hmac_secret="...")
+
+    # Handle requests (framework-agnostic):
+    status, response = await router.handle_tool_request(headers, body)
+"""
+
+__version__ = "0.1.0"
+
+from .circuit_breaker import CircuitBreakerService
+from .governance_engine import GovernanceEngine
+from .hmac_auth import sign_request, verify_hmac
+from .routes import AigpRouter
+from .scope_manager import ScopeEnvelopeManager, TEMPLATES
+from .store import GovernanceStore
+
+__all__ = [
+    "GovernanceEngine",
+    "GovernanceStore",
+    "ScopeEnvelopeManager",
+    "CircuitBreakerService",
+    "AigpRouter",
+    "TEMPLATES",
+    "verify_hmac",
+    "sign_request",
+]

aigp_server-0.1.0/aigp_server/circuit_breaker.py

@@ -0,0 +1,102 @@
+"""Circuit Breaker — halts anomalous agents, cascades to delegation chains."""
+
+import logging
+from datetime import datetime, timezone, timedelta
+
+from .store import GovernanceStore
+
+logger = logging.getLogger(__name__)
+
+CLOSED, OPEN, HALF_OPEN = "CLOSED", "OPEN", "HALF_OPEN"
+
+DEFAULT_CONFIG = {
+    "error_rate_threshold": 0.5,
+    "time_window_seconds": 60,
+    "cooldown_seconds": 30,
+    "max_probe_requests": 3,
+    "recovery_conditions": {"consecutive_successes": 3},
+}
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _expiry(seconds: int) -> str:
+    return (datetime.now(timezone.utc) + timedelta(seconds=seconds)).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+class CircuitBreakerService:
+    def __init__(self, db: GovernanceStore):
+        self.db = db
+
+    async def is_open(self, agent_id: str) -> bool:
+        state = await self.db.get_circuit_breaker(agent_id)
+        if not state:
+            return False
+        if state.get("state") == OPEN:
+            if _now() > state.get("cooldown_until", ""):
+                await self.db.update_circuit_breaker(agent_id, {"state": HALF_OPEN})
+                return False
+            return True
+        return False
+
+    async def get_state(self, agent_id: str) -> str:
+        state = await self.db.get_circuit_breaker(agent_id)
+        return state.get("state", CLOSED) if state else CLOSED
+
+    async def record_outcome(self, agent_id: str, success: bool):
+        state = await self.db.get_circuit_breaker(agent_id) or {
+            "state": CLOSED, "errors": 0, "total": 0, "consecutive_successes": 0,
+        }
+        state["total"] += 1
+        if not success:
+            state["errors"] += 1
+            state["consecutive_successes"] = 0
+        else:
+            state["consecutive_successes"] += 1
+
+        current = state.get("state", CLOSED)
+        config = await self._get_config(agent_id)
+
+        if current == CLOSED and state["total"] >= 5:
+            if state["errors"] / state["total"] > config["error_rate_threshold"]:
+                await self._trip(agent_id, config)
+                return
+
+        if current == HALF_OPEN and success:
+            if state["consecutive_successes"] >= config["recovery_conditions"]["consecutive_successes"]:
+                await self._reset(agent_id)
+                return
+
+        if current == HALF_OPEN and not success:
+            await self._trip(agent_id, config)
+            return
+
+        await self.db.put_circuit_breaker(agent_id, state)
+
+    async def manual_reset(self, agent_id: str):
+        await self._reset(agent_id)
+
+    async def _trip(self, agent_id: str, config: dict):
+        await self.db.put_circuit_breaker(agent_id, {
+            "state": OPEN,
+            "tripped_at": _now(),
+            "cooldown_until": _expiry(config["cooldown_seconds"]),
+            "errors": 0, "total": 0, "consecutive_successes": 0,
+        })
+        logger.warning("Circuit breaker TRIPPED for agent %s", agent_id)
+        # Cascade to delegates
+        for d in await self.db.get_delegates(agent_id):
+            if target := d.get("target_agent_id"):
+                await self._trip(target, config)
+        await self.db.put_task({"type": "CIRCUIT_BREAKER", "agent_id": agent_id, "status": "PENDING"})
+
+    async def _reset(self, agent_id: str):
+        await self.db.put_circuit_breaker(agent_id, {
+            "state": CLOSED, "errors": 0, "total": 0, "consecutive_successes": 0,
+        })
+
+    async def _get_config(self, agent_id: str) -> dict:
+        agent = await self.db.get_agent(agent_id)
+        return agent.get("circuit_breaker_config", DEFAULT_CONFIG) if agent else DEFAULT_CONFIG

aigp_server-0.1.0/aigp_server/governance_engine.py

@@ -0,0 +1,165 @@
+"""Governance Engine — evaluates AIGP agentic messages against scope envelopes."""
+
+import fnmatch
+import logging
+from datetime import datetime, timezone, timedelta
+from uuid import uuid4
+
+from .circuit_breaker import CircuitBreakerService
+from .scope_manager import ScopeEnvelopeManager, _now, _expiry
+from .store import GovernanceStore
+
+logger = logging.getLogger(__name__)
+
+
+class GovernanceEngine:
+    """Core AIGP decision engine. Mode: REPORT | REPORT-TRACE | ENFORCE."""
+
+    def __init__(self, db: GovernanceStore, scope_mgr: ScopeEnvelopeManager,
+                 circuit_breaker: CircuitBreakerService, mode: str = "REPORT"):
+        self.db = db
+        self.scope_mgr = scope_mgr
+        self.cb = circuit_breaker
+        self.mode = mode
+
+    async def handle_tool_request(self, msg: dict) -> dict:
+        agent_id = msg["agent_id"]
+        tool_id = msg["tool_id"]
+
+        if await self.cb.is_open(agent_id):
+            return self._decision("DENY", "CIRCUIT_OPEN", agent_id, tool_id)
+
+        envelope = await self.scope_mgr.get_active_envelope(agent_id)
+        if not envelope:
+            return self._decision("DENY", "NO_ACTIVE_SCOPE", agent_id, tool_id)
+
+        tools_perm = envelope.get("permissions", {}).get("tools", {})
+        if tool_id in tools_perm.get("denied", []):
+            return self._decision("DENY", "TOOL_DENIED", agent_id, tool_id)
+        if tools_perm.get("mode") == "allowlist" and tool_id not in tools_perm.get("allowed", []):
+            return self._decision("DENY", "TOOL_NOT_IN_ALLOWLIST", agent_id, tool_id)
+
+        budget = await self._check_budget(agent_id, envelope)
+        if not budget["ok"]:
+            return self._decision("DENY", f"BUDGET_DEPLETED:{budget['reason']}", agent_id, tool_id)
+
+        await self.db.increment_budget(agent_id, actions=1)
+        return self._decision("ALLOW", None, agent_id, tool_id, budget_remaining=budget["remaining"])
+
+    async def handle_plan_submit(self, msg: dict) -> dict:
+        agent_id = msg["agent_id"]
+        envelope = await self.scope_mgr.get_active_envelope(agent_id)
+        if not envelope:
+            return {"decision": "REJECTED", "plan_id": msg.get("plan_id"), "reason": "NO_ACTIVE_SCOPE"}
+
+        allowed_tools = set(envelope.get("permissions", {}).get("tools", {}).get("allowed", []))
+        modifications = []
+        for step in msg.get("steps", []):
+            tool_id = step.get("tool_id", "")
+            if tool_id and tool_id not in allowed_tools:
+                return {"decision": "REJECTED", "plan_id": msg["plan_id"], "reason": f"Tool '{tool_id}' not in scope"}
+            for gate in envelope.get("approval_gates", []):
+                if fnmatch.fnmatch(tool_id, gate.get("action_pattern", "")):
+                    modifications.append({"step_number": step["step_number"], "gate": gate["requires"], "reason": f"Matches: {gate['action_pattern']}"})
+
+        if modifications:
+            return {"decision": "APPROVED_WITH_MODIFICATIONS", "plan_id": msg["plan_id"], "modifications": modifications}
+        return {"decision": "APPROVED", "plan_id": msg["plan_id"]}
+
+    async def handle_step_complete(self, msg: dict) -> dict:
+        agent_id = msg["agent_id"]
+        await self.db.increment_budget(agent_id, tokens=msg.get("tokens_used", 0))
+        await self.cb.record_outcome(agent_id, msg.get("status") == "SUCCESS")
+        run_id = msg.get("plan_id", msg.get("run_id", ""))
+        if run_id:
+            await self.db.put_run_step(run_id, {"step_number": msg.get("step_number", 0), "status": msg.get("status", ""), "tokens_used": msg.get("tokens_used", 0)})
+        return {"status": "recorded"}
+
+    async def handle_escalate(self, msg: dict) -> dict:
+        task_id = await self.db.put_task({
+            "type": "ESCALATION", "agent_id": msg["agent_id"],
+            "escalation_id": msg.get("escalation_id", f"esc-{uuid4().hex[:8]}"),
+            "reason": msg.get("reason", ""), "action": msg.get("action", {}),
+            "context": msg.get("context", {}),
+            "timeout_seconds": msg.get("timeout_seconds", 300),
+            "timeout_action": msg.get("timeout_action", "DENY"), "status": "PENDING",
+        })
+        return {"status": "PAUSED", "task_id": task_id}
+
+    async def handle_delegate(self, msg: dict) -> dict:
+        parent_id = msg["delegating_agent_id"]
+        target_id = msg["target_agent_id"]
+        chain = msg.get("delegation_chain", [])
+
+        if len(chain) >= 5:
+            return {"decision": "DENIED", "reason": "MAX_DELEGATION_DEPTH_EXCEEDED"}
+
+        parent_scope = await self.scope_mgr.get_active_envelope(parent_id)
+        if not parent_scope:
+            return {"decision": "DENIED", "reason": "PARENT_NO_ACTIVE_SCOPE"}
+
+        requested = msg.get("requested_scope", {})
+        narrowed = self._intersect_scope(parent_scope, requested)
+        ttl = narrowed["budgets"].get("max_ttl_seconds", 1800)
+
+        await self.db.put_scope_envelope({
+            "scope_envelope_id": f"del-{uuid4().hex[:12]}",
+            "agent_id": target_id, "version": 1, "status": "ACTIVE",
+            "permissions": narrowed["permissions"], "budgets": narrowed["budgets"],
+            "autonomy_level": parent_scope.get("autonomy_level", "ACT_WITH_APPROVAL"),
+            "delegation_chain": chain + [parent_id],
+            "issued_at": _now(), "expires_at": _expiry(ttl),
+        })
+        await self.db.put_delegation({"delegating_agent_id": parent_id, "target_agent_id": target_id, "delegation_chain": chain + [parent_id]})
+        return {"decision": "ALLOWED", "target_agent_id": target_id, "narrowed_scope": narrowed}
+
+    async def handle_memory_write(self, msg: dict) -> dict:
+        agent_id = msg["agent_id"]
+        envelope = await self.scope_mgr.get_active_envelope(agent_id)
+        if not envelope:
+            return {"decision": "DENY", "reason": "NO_ACTIVE_SCOPE"}
+
+        mem_scope = envelope.get("memory_scope", {})
+        if not mem_scope.get("may_write", False):
+            return {"decision": "DENY", "reason": "MEMORY_WRITE_NOT_PERMITTED"}
+
+        classification = msg.get("data_classification", "HIGH")
+        allowed = mem_scope.get("allowed_classifications", [])
+        if allowed and classification not in allowed:
+            return {"decision": "DENY", "reason": f"CLASSIFICATION_{classification}_NOT_ALLOWED"}
+
+        max_ret = mem_scope.get("max_retention_seconds", 86400)
+        return {"decision": "ALLOW", "actual_retention_seconds": min(msg.get("retention_seconds", 86400), max_ret), "isolation": mem_scope.get("isolation", "AGENT_PRIVATE")}
+
+    def _decision(self, decision: str, reason: str | None, agent_id: str, tool_id: str, **extra) -> dict:
+        result = {"decision": decision, "reason": reason, "agent_id": agent_id, "tool_id": tool_id, **extra}
+        if self.mode in ("REPORT", "REPORT-TRACE") and decision == "DENY":
+            result["decision"] = "ALLOW"
+            result["report_only_denial"] = True
+            result["original_decision"] = "DENY"
+            result["original_reason"] = reason
+        return result
+
+    def _intersect_scope(self, parent: dict, requested: dict) -> dict:
+        parent_tools = set(parent.get("permissions", {}).get("tools", {}).get("allowed", []))
+        req_tools = set(requested.get("tools", []))
+        narrowed_tools = list(parent_tools & req_tools) if req_tools else list(parent_tools)
+        parent_budgets = parent.get("budgets", {})
+        return {
+            "permissions": {"tools": {"mode": "allowlist", "allowed": narrowed_tools}},
+            "budgets": {
+                "max_actions": min(requested.get("max_actions", 999), parent_budgets.get("max_actions", 999)),
+                "max_tokens": min(requested.get("max_tokens", 999999), parent_budgets.get("max_tokens", 999999)),
+                "max_cost_usd": min(requested.get("max_cost_usd", 99), parent_budgets.get("max_cost_usd", 99)),
+                "max_ttl_seconds": min(requested.get("max_ttl_seconds", 3600), parent_budgets.get("max_ttl_seconds", 3600)),
+            },
+        }
+
+    async def _check_budget(self, agent_id: str, envelope: dict) -> dict:
+        remaining = await self.db.get_budget_remaining(agent_id)
+        budgets = envelope.get("budgets", {})
+        if remaining.get("actions", 0) >= budgets.get("max_actions", 999):
+            return {"ok": False, "reason": "actions", "remaining": remaining}
+        if remaining.get("tokens", 0) >= budgets.get("max_tokens", 999999):
+            return {"ok": False, "reason": "tokens", "remaining": remaining}
+        return {"ok": True, "remaining": remaining}

aigp_server-0.1.0/aigp_server/hmac_auth.py

@@ -0,0 +1,54 @@
+"""HMAC-SHA256 authentication for AIGP protocol messages."""
+
+import hashlib
+import hmac
+import logging
+from datetime import datetime, timezone
+
+logger = logging.getLogger(__name__)
+
+MAX_TIMESTAMP_DRIFT_SECONDS = 300
+
+
+def verify_hmac(headers: dict, body: bytes, secret: str) -> bool:
+    """Verify AIGP HMAC-SHA256 signature.
+
+    Headers (case-insensitive):
+      X-AIGP-Signature: hmac-sha256={hex_digest}
+      X-AIGP-Timestamp: ISO 8601 timestamp
+      X-AIGP-Agent-Id: agent identifier
+    """
+    sig_header = headers.get("x-aigp-signature", "")
+    timestamp = headers.get("x-aigp-timestamp", "")
+
+    if not sig_header or not timestamp:
+        return False
+
+    try:
+        ts = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+        if abs((datetime.now(timezone.utc) - ts).total_seconds()) > MAX_TIMESTAMP_DRIFT_SECONDS:
+            return False
+    except (ValueError, TypeError):
+        return False
+
+    if not sig_header.startswith("hmac-sha256="):
+        return False
+
+    body_hash = hashlib.sha256(body).hexdigest()
+    message = f"{timestamp}\n{body_hash}"
+    expected = hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest()
+    return hmac.compare_digest(sig_header[len("hmac-sha256="):], expected)
+
+
+def sign_request(body: bytes, secret: str, agent_id: str) -> dict:
+    """Generate AIGP HMAC headers for outbound requests."""
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    body_hash = hashlib.sha256(body).hexdigest()
+    message = f"{timestamp}\n{body_hash}"
+    sig = hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest()
+    return {
+        "X-AIGP-Signature": f"hmac-sha256={sig}",
+        "X-AIGP-Timestamp": timestamp,
+        "X-AIGP-Agent-Id": agent_id,
+        "Content-Type": "application/json",
+    }

aigp_server-0.1.0/aigp_server/routes.py

@@ -0,0 +1,78 @@
+"""AIGP Server Routes — framework-agnostic handler functions.
+
+These return (status_code, response_dict) tuples. The host application
+(GOV_APP, RUN_PRJ) wraps them in its framework's response type.
+"""
+
+import json
+import logging
+
+from .governance_engine import GovernanceEngine
+from .hmac_auth import verify_hmac
+
+logger = logging.getLogger(__name__)
+
+
+class AigpRouter:
+    """Stateless router that delegates to GovernanceEngine."""
+
+    def __init__(self, engine: GovernanceEngine, hmac_secret: str = ""):
+        self.engine = engine
+        self.secret = hmac_secret
+
+    def _verify(self, headers: dict, body: bytes) -> dict | None:
+        """Verify HMAC and parse body. Returns parsed dict or None."""
+        if self.secret and not verify_hmac(headers, body, self.secret):
+            return None
+        try:
+            return json.loads(body)
+        except (json.JSONDecodeError, ValueError):
+            return None
+
+    async def handle_tool_request(self, headers: dict, body: bytes) -> tuple[int, dict]:
+        msg = self._verify(headers, body)
+        if msg is None:
+            return 401, {"error": "unauthorized"}
+        result = await self.engine.handle_tool_request(msg)
+        await self.engine.db.put_audit(msg.get("agent_id", ""), "TOOL_REQUEST", result["decision"], {"tool_id": msg.get("tool_id"), "reason": result.get("reason")})
+        return 200, result
+
+    async def handle_plan_submit(self, headers: dict, body: bytes) -> tuple[int, dict]:
+        msg = self._verify(headers, body)
+        if msg is None:
+            return 401, {"error": "unauthorized"}
+        result = await self.engine.handle_plan_submit(msg)
+        await self.engine.db.put_audit(msg.get("agent_id", ""), "PLAN_SUBMIT", result["decision"], msg)
+        return 200, result
+
+    async def handle_step_complete(self, headers: dict, body: bytes) -> tuple[int, dict]:
+        msg = self._verify(headers, body)
+        if msg is None:
+            return 401, {"error": "unauthorized"}
+        result = await self.engine.handle_step_complete(msg)
+        await self.engine.db.put_audit(msg.get("agent_id", ""), "STEP_COMPLETE", msg.get("status", ""), msg)
+        return 200, result
+
+    async def handle_escalate(self, headers: dict, body: bytes) -> tuple[int, dict]:
+        msg = self._verify(headers, body)
+        if msg is None:
+            return 401, {"error": "unauthorized"}
+        result = await self.engine.handle_escalate(msg)
+        await self.engine.db.put_audit(msg.get("agent_id", ""), "ESCALATE", result.get("status", ""), msg)
+        return 200, result
+
+    async def handle_delegate(self, headers: dict, body: bytes) -> tuple[int, dict]:
+        msg = self._verify(headers, body)
+        if msg is None:
+            return 401, {"error": "unauthorized"}
+        result = await self.engine.handle_delegate(msg)
+        await self.engine.db.put_audit(msg.get("delegating_agent_id", ""), "DELEGATE", result["decision"], msg)
+        return 200, result
+
+    async def handle_memory_write(self, headers: dict, body: bytes) -> tuple[int, dict]:
+        msg = self._verify(headers, body)
+        if msg is None:
+            return 401, {"error": "unauthorized"}
+        result = await self.engine.handle_memory_write(msg)
+        await self.engine.db.put_audit(msg.get("agent_id", ""), "MEMORY_WRITE", result["decision"], msg)
+        return 200, result

aigp_server-0.1.0/aigp_server/scope_manager.py

@@ -0,0 +1,99 @@
+"""Scope Envelope Manager — create, approve, enforce scope envelopes with SoD."""
+
+import copy
+import logging
+from datetime import datetime, timezone, timedelta
+from uuid import uuid4
+
+from .store import GovernanceStore
+
+logger = logging.getLogger(__name__)
+
+TEMPLATES = {
+    "ANALYST": {
+        "permissions": {"tools": {"mode": "allowlist", "allowed": []}, "models": {"mode": "allowlist", "allowed": ["us.anthropic.claude-sonnet-4-5-20250929-v1:0"]}},
+        "budgets": {"max_actions": 100, "max_tokens": 200000, "max_cost_usd": 10.0, "max_ttl_seconds": 3600},
+        "autonomy_level": "ACT_AUTONOMOUS",
+        "memory_scope": {"may_write": False},
+    },
+    "EXECUTOR": {
+        "permissions": {"tools": {"mode": "allowlist", "allowed": []}, "models": {"mode": "allowlist", "allowed": ["us.anthropic.claude-sonnet-4-5-20250929-v1:0"]}},
+        "budgets": {"max_actions": 50, "max_tokens": 100000, "max_cost_usd": 5.0, "max_ttl_seconds": 3600},
+        "autonomy_level": "ACT_WITH_APPROVAL",
+        "approval_gates": [{"action_pattern": "*_delete_*", "requires": "HUMAN_APPROVAL", "timeout_seconds": 300, "timeout_action": "DENY"}],
+        "memory_scope": {"may_write": True, "max_retention_seconds": 86400, "allowed_classifications": ["LOW", "MEDIUM"], "isolation": "AGENT_PRIVATE"},
+    },
+    "ORCHESTRATOR": {
+        "permissions": {"tools": {"mode": "allowlist", "allowed": []}, "models": {"mode": "allowlist", "allowed": ["us.anthropic.claude-opus-4-7"]}},
+        "budgets": {"max_actions": 200, "max_tokens": 500000, "max_cost_usd": 25.0, "max_ttl_seconds": 3600},
+        "autonomy_level": "ACT_WITH_APPROVAL",
+        "memory_scope": {"may_write": True, "max_retention_seconds": 3600, "allowed_classifications": ["LOW", "MEDIUM", "HIGH"], "isolation": "APP_SHARED"},
+    },
+}
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _expiry(ttl_seconds: int) -> str:
+    return (datetime.now(timezone.utc) + timedelta(seconds=ttl_seconds)).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+class ScopeEnvelopeManager:
+    def __init__(self, db: GovernanceStore):
+        self.db = db
+
+    async def create_request(self, agent_id: str, envelope: dict, requester: str) -> str:
+        envelope_id = f"scope-{uuid4().hex[:12]}"
+        version = len(await self.db.query_scopes(agent_id)) + 1
+        envelope.update({
+            "scope_envelope_id": envelope_id,
+            "agent_id": agent_id,
+            "version": version,
+            "status": "PENDING_APPROVAL",
+            "created_by": requester,
+            "created_at": _now(),
+        })
+        await self.db.put_scope_envelope(envelope)
+        task_id = await self.db.put_task({
+            "type": "SCOPE_APPROVAL", "agent_id": agent_id,
+            "envelope_id": envelope_id, "requester": requester, "status": "PENDING",
+        })
+        return task_id
+
+    async def approve(self, envelope_id: str, approver: str) -> bool:
+        envelope = await self.db.get_scope_envelope(envelope_id)
+        if not envelope:
+            raise ValueError("Envelope not found")
+        if envelope["created_by"] == approver:
+            raise PermissionError("SoD violation: approver cannot be the creator")
+        ttl = envelope.get("budgets", {}).get("max_ttl_seconds", 3600)
+        await self.db.update_scope_envelope(envelope_id, {
+            "status": "ACTIVE", "approved_by": approver,
+            "issued_at": _now(), "expires_at": _expiry(ttl),
+        })
+        return True
+
+    async def reject(self, envelope_id: str, rejector: str, reason: str = "") -> bool:
+        await self.db.update_scope_envelope(envelope_id, {
+            "status": "REJECTED", "rejected_by": rejector,
+            "rejection_reason": reason, "rejected_at": _now(),
+        })
+        return True
+
+    async def get_active_envelope(self, agent_id: str) -> dict | None:
+        envelope = await self.db.get_active_scope(agent_id)
+        if not envelope:
+            return None
+        if envelope.get("expires_at", "") and envelope["expires_at"] < _now():
+            await self.db.update_scope_envelope(envelope["scope_envelope_id"], {"status": "EXPIRED"})
+            return None
+        return envelope
+
+    async def from_template(self, template_name: str, agent_id: str, tools: list[str] | None = None) -> dict:
+        envelope = copy.deepcopy(TEMPLATES.get(template_name, TEMPLATES["EXECUTOR"]))
+        if tools:
+            envelope["permissions"]["tools"]["allowed"] = tools
+        envelope["agent_id"] = agent_id
+        return envelope

aigp_server-0.1.0/aigp_server/store.py

@@ -0,0 +1,78 @@
+"""Storage protocol — abstract interface that host applications must implement."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class GovernanceStore(ABC):
+    """Abstract storage backend for the AIGP governance server.
+
+    Host applications (GOV_APP, RUN_PRJ) implement this interface
+    to provide persistence for scope envelopes, circuit breakers,
+    budgets, delegations, audits, and tasks.
+    """
+
+    # --- Scope Envelopes ---
+
+    @abstractmethod
+    async def put_scope_envelope(self, envelope: dict) -> None: ...
+
+    @abstractmethod
+    async def get_scope_envelope(self, envelope_id: str) -> dict | None: ...
+
+    @abstractmethod
+    async def get_active_scope(self, agent_id: str) -> dict | None: ...
+
+    @abstractmethod
+    async def update_scope_envelope(self, envelope_id: str, updates: dict) -> None: ...
+
+    @abstractmethod
+    async def query_scopes(self, agent_id: str) -> list[dict]: ...
+
+    # --- Circuit Breaker ---
+
+    @abstractmethod
+    async def get_circuit_breaker(self, agent_id: str) -> dict | None: ...
+
+    @abstractmethod
+    async def put_circuit_breaker(self, agent_id: str, state: dict) -> None: ...
+
+    @abstractmethod
+    async def update_circuit_breaker(self, agent_id: str, updates: dict) -> None: ...
+
+    # --- Budget ---
+
+    @abstractmethod
+    async def increment_budget(self, agent_id: str, actions: int = 0, tokens: int = 0) -> None: ...
+
+    @abstractmethod
+    async def get_budget_remaining(self, agent_id: str) -> dict: ...
+
+    # --- Delegation ---
+
+    @abstractmethod
+    async def put_delegation(self, delegation: dict) -> None: ...
+
+    @abstractmethod
+    async def get_delegates(self, agent_id: str) -> list[dict]: ...
+
+    # --- Agent ---
+
+    @abstractmethod
+    async def get_agent(self, agent_id: str) -> dict | None: ...
+
+    # --- Tasks (escalations, approvals) ---
+
+    @abstractmethod
+    async def put_task(self, task: dict) -> str: ...
+
+    # --- Audit ---
+
+    @abstractmethod
+    async def put_audit(self, agent_id: str, action: str, decision: str, details: dict) -> None: ...
+
+    # --- Run Steps ---
+
+    @abstractmethod
+    async def put_run_step(self, run_id: str, step: dict) -> None: ...

aigp_server-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aigp-server"
+version = "0.1.0"
+description = "AIGP Governance Server — agentic governance engine (scope envelopes, circuit breakers, delegation)"
+requires-python = ">=3.11"
+dependencies = []
+license = {text = "Proprietary"}
+authors = [{name = "Evan Erwee", email = "evan@erwee.com"}]
+readme = "README.md"
+keywords = ["ai", "governance", "protocol", "aigp", "agentic", "scope-envelope", "circuit-breaker"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Security",
+]
+
+[project.urls]
+Homepage = "https://github.com/owner-spec/aigp-protocol"
+Repository = "https://github.com/owner-spec/aigp-protocol"
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio"]