darm-guard 0.1.0__tar.gz

darm_guard-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: darm-guard
+Version: 0.1.0
+Summary: Formally verified agent tool-authorization governance
+Author: Olusanya Gbolahan V
+License: MIT
+Project-URL: Formal Backing, https://github.com/Goblohan/darm-monitor
+Project-URL: Source, https://github.com/Goblohan/Darm-Guard
+Keywords: ai-safety,agent-governance,formal-verification
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# DARM Guard
+
+**See what your agent is doing. Then govern it.**
+
+Formally verified agent tool-authorization governance, backed by 1,001 Lean 4 theorems.
+
+*PerceptraAI Lab*
+
+## Install
+
+From source:
+
+    git clone https://github.com/Goblohan/Darm-Guard.git
+    cd Darm-Guard
+    pip install -e .
+
+## Quick Start
+
+    from darm_guard import DARMGuard, Policy, Credential
+
+    guard = DARMGuard(
+        policy=Policy(authorized_tools=frozenset(["file_read", "web_search"])),
+        credential=Credential(tools=frozenset(["file_read"])),
+    )
+
+    result = guard.check({"file_read"})   # admitted, within credential
+    result = guard.check({"code_exec"})   # admitted (OBSERVE), but alerts drift
+
+## Three Modes
+
+**OBSERVE (default)** -- Agent runs normally. Every tool call logged. Drift detected and alerted. Nothing blocked.
+
+**GOVERN** -- Unauthorized tools blocked with typed ODATS diagnosis.
+
+**ENFORCE** -- Same as GOVERN plus signed audit trail to log file.
+
+    from darm_guard import Mode
+
+    guard = DARMGuard(policy=p, credential=c, mode=Mode.GOVERN)
+    result = guard.check({"code_exec"})
+    # admitted=False
+    # Rejected:
+    #   O-failure: code_exec -- not in observation model
+
+## ODATS Diagnosis
+
+Every rejection identifies WHICH condition failed:
+
+| Code | Condition | Meaning |
+|------|-----------|---------|
+| **O** | Observation | Tool not in the observation model |
+| **D** | Domain Completeness | Dependency outside represented domain |
+| **A** | Authority | Tool known but not authorized |
+| **T** | Temporal Freshness | Credential expired |
+| **S** | Semantic Boundary | Resolution mismatch |
+
+Each condition is backed by a deletion-minimality witness proving it independently necessary.
+
+## Session Scope Tracking
+
+Tracks cumulative scope across a session, not just per-call. Individually authorized calls can compose into unauthorized workflows.
+
+    guard.check({"file_read"})       # within credential
+    guard.check({"web_search"})      # outside credential, authorized by policy
+    print(guard.scope())             # shows cumulative drift
+
+## Temporal Freshness
+
+Credentials can expire. DARM Guard detects stale credentials automatically.
+
+    from datetime import datetime, timedelta
+
+    cred = Credential(
+        tools=frozenset(["file_read"]),
+        issued_at=datetime(2026, 9, 1),
+        ttl=timedelta(hours=4),
+    )
+    guard = DARMGuard(policy=p, credential=cred, mode=Mode.GOVERN)
+
+    guard.check({"file_read"}, now=datetime(2026, 9, 1, 2))   # admitted (within TTL)
+    guard.check({"file_read"}, now=datetime(2026, 9, 1, 5))   # rejected (T-failure)
+
+## Credential Escalation
+
+    guard.update_credential({"code_exec"})   # human-approved expansion
+
+## Audit Trail
+
+    import json
+    for entry in guard.audit():
+        print(json.dumps(entry))
+
+## LangChain Integration
+
+    from darm_guard.integrations import guard_tools
+    guarded = guard_tools(agent.tools, guard=my_guard)
+
+## Formal Backing
+
+Every check maps to a Lean 4 theorem in [darm-monitor](https://github.com/Goblohan/darm-monitor):
+
+| Theorem | What it proves | File |
+|---------|---------------|------|
+| target_assured_of_source_and_delta | Conservation: Source + Delta -> Target | R5AssuranceConservation |
+| ag_is_satisfied + causal_safety_fails | O is necessary | E14AGContractComparison |
+| unsupported_authority_substitution | A is necessary | R4bAuthoritySubstitution |
+| temporal_freshness_independently_necessary | T is necessary | E16TemporalFreshness |
+| proposal_authority_separation | Proposal != Authority | E17ProposalAuthoritySeparation |
+| check_true_implies_obligation | Bool check == Prop obligation | E21ExecutableObligationBridge |
+
+167 modules. 31,553 lines. 1,001 theorems. Zero sorry.
+
+## What Makes DARM Guard Different
+
+**Formally verified rejection logic.** Not tested -- proved.
+
+**Session scope tracking.** Cumulative drift, not per-call.
+
+**ODATS diagnostic vocabulary.** Typed diagnoses, not "permission denied."
+
+**Three-mode progressive adoption.** Visibility first, governance when ready.
+
+**Intent-agnostic.** Same structural rejection for benign and malicious agents.
+
+## License
+
+MIT
+
+---
+
+**Olusanya Gbolahan V** -- **PerceptraAI Lab**
+
+[darm-monitor](https://github.com/Goblohan/darm-monitor) | [Darm-Guard](https://github.com/Goblohan/Darm-Guard)

darm_guard-0.1.0/README.md

@@ -0,0 +1,133 @@
+# DARM Guard
+
+**See what your agent is doing. Then govern it.**
+
+Formally verified agent tool-authorization governance, backed by 1,001 Lean 4 theorems.
+
+*PerceptraAI Lab*
+
+## Install
+
+From source:
+
+    git clone https://github.com/Goblohan/Darm-Guard.git
+    cd Darm-Guard
+    pip install -e .
+
+## Quick Start
+
+    from darm_guard import DARMGuard, Policy, Credential
+
+    guard = DARMGuard(
+        policy=Policy(authorized_tools=frozenset(["file_read", "web_search"])),
+        credential=Credential(tools=frozenset(["file_read"])),
+    )
+
+    result = guard.check({"file_read"})   # admitted, within credential
+    result = guard.check({"code_exec"})   # admitted (OBSERVE), but alerts drift
+
+## Three Modes
+
+**OBSERVE (default)** -- Agent runs normally. Every tool call logged. Drift detected and alerted. Nothing blocked.
+
+**GOVERN** -- Unauthorized tools blocked with typed ODATS diagnosis.
+
+**ENFORCE** -- Same as GOVERN plus signed audit trail to log file.
+
+    from darm_guard import Mode
+
+    guard = DARMGuard(policy=p, credential=c, mode=Mode.GOVERN)
+    result = guard.check({"code_exec"})
+    # admitted=False
+    # Rejected:
+    #   O-failure: code_exec -- not in observation model
+
+## ODATS Diagnosis
+
+Every rejection identifies WHICH condition failed:
+
+| Code | Condition | Meaning |
+|------|-----------|---------|
+| **O** | Observation | Tool not in the observation model |
+| **D** | Domain Completeness | Dependency outside represented domain |
+| **A** | Authority | Tool known but not authorized |
+| **T** | Temporal Freshness | Credential expired |
+| **S** | Semantic Boundary | Resolution mismatch |
+
+Each condition is backed by a deletion-minimality witness proving it independently necessary.
+
+## Session Scope Tracking
+
+Tracks cumulative scope across a session, not just per-call. Individually authorized calls can compose into unauthorized workflows.
+
+    guard.check({"file_read"})       # within credential
+    guard.check({"web_search"})      # outside credential, authorized by policy
+    print(guard.scope())             # shows cumulative drift
+
+## Temporal Freshness
+
+Credentials can expire. DARM Guard detects stale credentials automatically.
+
+    from datetime import datetime, timedelta
+
+    cred = Credential(
+        tools=frozenset(["file_read"]),
+        issued_at=datetime(2026, 9, 1),
+        ttl=timedelta(hours=4),
+    )
+    guard = DARMGuard(policy=p, credential=cred, mode=Mode.GOVERN)
+
+    guard.check({"file_read"}, now=datetime(2026, 9, 1, 2))   # admitted (within TTL)
+    guard.check({"file_read"}, now=datetime(2026, 9, 1, 5))   # rejected (T-failure)
+
+## Credential Escalation
+
+    guard.update_credential({"code_exec"})   # human-approved expansion
+
+## Audit Trail
+
+    import json
+    for entry in guard.audit():
+        print(json.dumps(entry))
+
+## LangChain Integration
+
+    from darm_guard.integrations import guard_tools
+    guarded = guard_tools(agent.tools, guard=my_guard)
+
+## Formal Backing
+
+Every check maps to a Lean 4 theorem in [darm-monitor](https://github.com/Goblohan/darm-monitor):
+
+| Theorem | What it proves | File |
+|---------|---------------|------|
+| target_assured_of_source_and_delta | Conservation: Source + Delta -> Target | R5AssuranceConservation |
+| ag_is_satisfied + causal_safety_fails | O is necessary | E14AGContractComparison |
+| unsupported_authority_substitution | A is necessary | R4bAuthoritySubstitution |
+| temporal_freshness_independently_necessary | T is necessary | E16TemporalFreshness |
+| proposal_authority_separation | Proposal != Authority | E17ProposalAuthoritySeparation |
+| check_true_implies_obligation | Bool check == Prop obligation | E21ExecutableObligationBridge |
+
+167 modules. 31,553 lines. 1,001 theorems. Zero sorry.
+
+## What Makes DARM Guard Different
+
+**Formally verified rejection logic.** Not tested -- proved.
+
+**Session scope tracking.** Cumulative drift, not per-call.
+
+**ODATS diagnostic vocabulary.** Typed diagnoses, not "permission denied."
+
+**Three-mode progressive adoption.** Visibility first, governance when ready.
+
+**Intent-agnostic.** Same structural rejection for benign and malicious agents.
+
+## License
+
+MIT
+
+---
+
+**Olusanya Gbolahan V** -- **PerceptraAI Lab**
+
+[darm-monitor](https://github.com/Goblohan/darm-monitor) | [Darm-Guard](https://github.com/Goblohan/Darm-Guard)

darm_guard-0.1.0/darm_guard/__init__.py

@@ -0,0 +1,13 @@
+"""DARM Guard - Formally verified agent tool-authorization governance."""
+
+from .types import FailureKind, FailureWitness, DriftLevel, Credential, Policy, TransferResult
+from .guard import DARMGuard, Mode
+from .session import Session, SessionEvent
+from .checker import check_transfer
+
+__version__ = "0.1.0"
+__all__ = [
+    "DARMGuard", "Mode", "Policy", "Credential", "TransferResult",
+    "FailureKind", "FailureWitness", "DriftLevel",
+    "Session", "SessionEvent", "check_transfer",
+]

darm_guard-0.1.0/darm_guard/checker.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+from typing import FrozenSet, Optional, List
+from datetime import datetime
+from .types import Credential, Policy, FailureKind, FailureWitness, TransferResult, DriftLevel
+
+
+def check_transfer(
+    credential: Credential,
+    requested_tools: FrozenSet[str],
+    policy: Policy,
+    now: Optional[datetime] = None,
+) -> TransferResult:
+    now = now or datetime.utcnow()
+    delta = requested_tools - credential.tools
+    failures: List[FailureWitness] = []
+
+    if credential.is_expired(now):
+        failures.append(FailureWitness(
+            kind=FailureKind.TEMPORAL_FRESHNESS,
+            tool="*",
+            detail=f"credential expired (issued {credential.issued_at}, ttl {credential.ttl})",
+        ))
+
+    unknown_tools = requested_tools - policy.authorized_tools - credential.tools
+    for tool in sorted(unknown_tools):
+        failures.append(FailureWitness(
+            kind=FailureKind.OBSERVATION,
+            tool=tool,
+            detail=f"not in observation model (unknown to policy at boundary '{policy.boundary}')",
+        ))
+
+    for tool in sorted(delta):
+        if tool in unknown_tools:
+            continue
+        if tool not in policy.authorized_tools:
+            failures.append(FailureWitness(
+                kind=FailureKind.AUTHORITY,
+                tool=tool,
+                detail=f"not authorized at boundary '{policy.boundary}'",
+            ))
+
+    if not delta:
+        drift = DriftLevel.WITHIN
+    elif not failures:
+        drift = DriftLevel.DRIFT
+    else:
+        drift = DriftLevel.VIOLATION
+
+    return TransferResult(
+        admitted=len(failures) == 0,
+        drift=drift,
+        delta=delta,
+        failures=failures,
+        timestamp=now,
+    )

darm_guard-0.1.0/darm_guard/dashboard.py

@@ -0,0 +1,57 @@
+import http.server
+import json
+import os
+import threading
+import webbrowser
+from typing import Optional
+from .guard import DARMGuard
+
+
+class DashboardHandler(http.server.SimpleHTTPRequestHandler):
+    guard: Optional[DARMGuard] = None
+    dashboard_dir: str = ""
+
+    def do_GET(self):
+        if self.path == "/api/state":
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.end_headers()
+            state = {
+                "mode": self.guard.mode.name if self.guard else "UNKNOWN",
+                "scope": self.guard.scope() if self.guard else {},
+                "audit": self.guard.audit() if self.guard else [],
+                "policy_tools": sorted(self.guard.policy.authorized_tools) if self.guard else [],
+            }
+            self.wfile.write(json.dumps(state).encode())
+            return
+        if self.path == "/" or self.path == "/index.html":
+            self.path = "/index.html"
+        self.directory = self.dashboard_dir
+        super().do_GET()
+
+    def log_message(self, format, *args):
+        pass
+
+
+def serve_dashboard(guard: DARMGuard, port: int = 7832, open_browser: bool = True):
+    dashboard_dir = os.path.join(os.path.dirname(__file__), "..", "dashboard")
+    dashboard_dir = os.path.abspath(dashboard_dir)
+    DashboardHandler.guard = guard
+    DashboardHandler.dashboard_dir = dashboard_dir
+    server = http.server.HTTPServer(("127.0.0.1", port), DashboardHandler)
+    print(f"DARM Guard dashboard: http://127.0.0.1:{port}")
+    if open_browser:
+        webbrowser.open(f"http://127.0.0.1:{port}")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\nDashboard stopped.")
+        server.server_close()
+
+
+def serve_dashboard_background(guard: DARMGuard, port: int = 7832):
+    t = threading.Thread(target=serve_dashboard, args=(guard, port, False), daemon=True)
+    t.start()
+    print(f"DARM Guard dashboard (background): http://127.0.0.1:{port}")
+    return t

darm_guard-0.1.0/darm_guard/guard.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+from enum import Enum, auto
+from typing import FrozenSet, Optional, Set
+from datetime import datetime
+import json
+import sys
+from .types import Credential, Policy, TransferResult, DriftLevel
+from .session import Session
+
+
+class Mode(Enum):
+    OBSERVE = auto()
+    GOVERN = auto()
+    ENFORCE = auto()
+
+
+class DARMGuard:
+    def __init__(self, policy: Policy, credential: Credential,
+                 mode: Mode = Mode.OBSERVE, session_id: str = "",
+                 log_file: Optional[str] = None):
+        self.policy = policy
+        self.credential = credential
+        self.mode = mode
+        self.session = Session(credential, policy, session_id)
+        self._log_file = log_file
+        self._stderr_alerts = True
+
+    def check(self, requested_tools: Set[str], now: Optional[datetime] = None) -> TransferResult:
+        tools = frozenset(requested_tools)
+        result = self.session.check(tools, now)
+
+        if self.mode == Mode.OBSERVE:
+            observed_result = TransferResult(
+                admitted=True, drift=result.drift,
+                delta=result.delta, failures=result.failures, timestamp=result.timestamp,
+            )
+            self._log_event(result)
+            self._alert(result)
+            return observed_result
+
+        self._log_event(result)
+        self._alert(result)
+        return result
+
+    def update_credential(self, new_tools: Set[str]) -> None:
+        expanded = self.credential.tools | frozenset(new_tools)
+        self.credential = Credential(
+            tools=expanded, actor=self.credential.actor,
+            boundary=self.credential.boundary,
+            issued_at=self.credential.issued_at, ttl=self.credential.ttl,
+        )
+        self.session.credential = self.credential
+
+    def scope(self) -> dict:
+        return self.session.scope_summary()
+
+    def audit(self) -> list:
+        return self.session.audit_trail()
+
+    def _log_event(self, result: TransferResult) -> None:
+        if self._log_file is None:
+            return
+        event = self.session.log[-1] if self.session.log else None
+        if event is None:
+            return
+        entry = {
+            "timestamp": event.timestamp.isoformat(),
+            "mode": self.mode.name,
+            "requested": sorted(event.requested_tools),
+            "admitted": result.admitted,
+            "drift": result.drift.name,
+            "failures": [
+                {"kind": f.kind.name, "tool": f.tool, "detail": f.detail}
+                for f in result.failures
+            ],
+        }
+        try:
+            with open(self._log_file, "a") as f:
+                f.write(json.dumps(entry) + "\n")
+        except OSError:
+            pass
+
+    def _alert(self, result: TransferResult) -> None:
+        if not self._stderr_alerts:
+            return
+        if result.drift == DriftLevel.WITHIN:
+            return
+        if result.drift == DriftLevel.DRIFT:
+            print(f"[DARM DRIFT] {', '.join(sorted(result.delta))} outside credential scope", file=sys.stderr)
+        elif result.drift == DriftLevel.VIOLATION:
+            for f in result.failures:
+                print(f"[DARM REJECT] {f.explain()}", file=sys.stderr)

darm_guard-0.1.0/darm_guard/integrations/__init__.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+from typing import Any, List
+from ..guard import DARMGuard
+
+
+def guard_tools(tools: List[Any], guard: DARMGuard) -> List[Any]:
+    wrapped = []
+    for tool in tools:
+        wrapped.append(_GuardedTool(tool, guard))
+    return wrapped
+
+
+class _GuardedTool:
+    def __init__(self, tool: Any, guard: DARMGuard):
+        self._tool = tool
+        self._guard = guard
+        self.name = getattr(tool, "name", str(tool))
+        self.description = getattr(tool, "description", "")
+
+    def run(self, *args: Any, **kwargs: Any) -> Any:
+        result = self._guard.check({self.name})
+        if not result:
+            raise PermissionError(result.explain())
+        return self._tool.run(*args, **kwargs)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self.run(*args, **kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._tool, name)

darm_guard-0.1.0/darm_guard/session.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import FrozenSet, List, Optional, Callable
+from datetime import datetime
+from .types import Credential, Policy, TransferResult, DriftLevel
+from .checker import check_transfer
+
+
+@dataclass
+class SessionEvent:
+    timestamp: datetime
+    requested_tools: FrozenSet[str]
+    cumulative_scope: FrozenSet[str]
+    result: TransferResult
+
+
+class Session:
+    def __init__(self, credential: Credential, policy: Policy, session_id: str = ""):
+        self.credential = credential
+        self.policy = policy
+        self.session_id = session_id
+        self.cumulative_scope: FrozenSet[str] = frozenset()
+        self.log: List[SessionEvent] = []
+        self._on_drift: Optional[Callable[[SessionEvent], None]] = None
+        self._on_violation: Optional[Callable[[SessionEvent], None]] = None
+
+    def on_drift(self, callback: Callable[[SessionEvent], None]) -> None:
+        self._on_drift = callback
+
+    def on_violation(self, callback: Callable[[SessionEvent], None]) -> None:
+        self._on_violation = callback
+
+    def check(self, requested_tools: FrozenSet[str], now: Optional[datetime] = None) -> TransferResult:
+        now = now or datetime.utcnow()
+        result = check_transfer(self.credential, requested_tools, self.policy, now)
+        new_scope = self.cumulative_scope | requested_tools
+        self.cumulative_scope = new_scope
+
+        cumulative_delta = self.cumulative_scope - self.credential.tools
+        if cumulative_delta and result.drift == DriftLevel.WITHIN:
+            result = TransferResult(
+                admitted=result.admitted, drift=DriftLevel.DRIFT,
+                delta=result.delta, failures=result.failures, timestamp=result.timestamp,
+            )
+
+        event = SessionEvent(
+            timestamp=now, requested_tools=requested_tools,
+            cumulative_scope=self.cumulative_scope, result=result,
+        )
+        self.log.append(event)
+
+        if result.drift == DriftLevel.DRIFT and self._on_drift:
+            self._on_drift(event)
+        if result.drift == DriftLevel.VIOLATION and self._on_violation:
+            self._on_violation(event)
+
+        return result
+
+    def scope_summary(self) -> dict:
+        delta = self.cumulative_scope - self.credential.tools
+        return {
+            "session_id": self.session_id,
+            "credential_scope": sorted(self.credential.tools),
+            "cumulative_scope": sorted(self.cumulative_scope),
+            "delta": sorted(delta),
+            "drift": bool(delta),
+            "call_count": len(self.log),
+            "violations": sum(1 for e in self.log if e.result.drift == DriftLevel.VIOLATION),
+        }
+
+    def audit_trail(self) -> List[dict]:
+        return [
+            {
+                "timestamp": e.timestamp.isoformat(),
+                "requested": sorted(e.requested_tools),
+                "cumulative": sorted(e.cumulative_scope),
+                "admitted": e.result.admitted,
+                "drift": e.result.drift.name,
+                "delta": sorted(e.result.delta),
+                "failures": [
+                    {"kind": f.kind.name, "tool": f.tool, "detail": f.detail}
+                    for f in e.result.failures
+                ],
+            }
+            for e in self.log
+        ]

darm_guard-0.1.0/darm_guard/types.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import FrozenSet, List, Optional
+from datetime import datetime, timedelta
+
+
+class FailureKind(Enum):
+    OBSERVATION = auto()
+    DOMAIN_COMPLETENESS = auto()
+    AUTHORITY = auto()
+    TEMPORAL_FRESHNESS = auto()
+    SEMANTIC_BOUNDARY = auto()
+
+
+class DriftLevel(Enum):
+    WITHIN = auto()
+    DRIFT = auto()
+    VIOLATION = auto()
+
+
+@dataclass(frozen=True)
+class FailureWitness:
+    kind: FailureKind
+    tool: str
+    detail: str
+
+    def explain(self) -> str:
+        labels = {
+            FailureKind.OBSERVATION: "O-failure",
+            FailureKind.DOMAIN_COMPLETENESS: "D-failure",
+            FailureKind.AUTHORITY: "A-failure",
+            FailureKind.TEMPORAL_FRESHNESS: "T-failure",
+            FailureKind.SEMANTIC_BOUNDARY: "S-failure",
+        }
+        return f"{labels[self.kind]}: {self.tool} -- {self.detail}"
+
+
+@dataclass(frozen=True)
+class Credential:
+    tools: FrozenSet[str]
+    actor: str = ""
+    boundary: str = "default"
+    issued_at: Optional[datetime] = None
+    ttl: Optional[timedelta] = None
+
+    def is_expired(self, now: Optional[datetime] = None) -> bool:
+        if self.issued_at is None or self.ttl is None:
+            return False
+        now = now or datetime.utcnow()
+        return now > self.issued_at + self.ttl
+
+
+@dataclass(frozen=True)
+class Policy:
+    authorized_tools: FrozenSet[str]
+    boundary: str = "default"
+
+
+@dataclass
+class TransferResult:
+    admitted: bool
+    drift: DriftLevel
+    delta: FrozenSet[str] = field(default_factory=frozenset)
+    failures: List[FailureWitness] = field(default_factory=list)
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+
+    def __bool__(self) -> bool:
+        return self.admitted
+
+    def explain(self) -> str:
+        if self.admitted:
+            if self.drift == DriftLevel.DRIFT:
+                return f"Admitted with drift: {', '.join(sorted(self.delta))} outside credential but authorized."
+            return "Admitted: all obligations discharged."
+        lines = ["Rejected:"]
+        for f in self.failures:
+            lines.append(f"  {f.explain()}")
+        return "\n".join(lines)

darm_guard-0.1.0/darm_guard.egg-info/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: darm-guard
+Version: 0.1.0
+Summary: Formally verified agent tool-authorization governance
+Author: Olusanya Gbolahan V
+License: MIT
+Project-URL: Formal Backing, https://github.com/Goblohan/darm-monitor
+Project-URL: Source, https://github.com/Goblohan/Darm-Guard
+Keywords: ai-safety,agent-governance,formal-verification
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# DARM Guard
+
+**See what your agent is doing. Then govern it.**
+
+Formally verified agent tool-authorization governance, backed by 1,001 Lean 4 theorems.
+
+*PerceptraAI Lab*
+
+## Install
+
+From source:
+
+    git clone https://github.com/Goblohan/Darm-Guard.git
+    cd Darm-Guard
+    pip install -e .
+
+## Quick Start
+
+    from darm_guard import DARMGuard, Policy, Credential
+
+    guard = DARMGuard(
+        policy=Policy(authorized_tools=frozenset(["file_read", "web_search"])),
+        credential=Credential(tools=frozenset(["file_read"])),
+    )
+
+    result = guard.check({"file_read"})   # admitted, within credential
+    result = guard.check({"code_exec"})   # admitted (OBSERVE), but alerts drift
+
+## Three Modes
+
+**OBSERVE (default)** -- Agent runs normally. Every tool call logged. Drift detected and alerted. Nothing blocked.
+
+**GOVERN** -- Unauthorized tools blocked with typed ODATS diagnosis.
+
+**ENFORCE** -- Same as GOVERN plus signed audit trail to log file.
+
+    from darm_guard import Mode
+
+    guard = DARMGuard(policy=p, credential=c, mode=Mode.GOVERN)
+    result = guard.check({"code_exec"})
+    # admitted=False
+    # Rejected:
+    #   O-failure: code_exec -- not in observation model
+
+## ODATS Diagnosis
+
+Every rejection identifies WHICH condition failed:
+
+| Code | Condition | Meaning |
+|------|-----------|---------|
+| **O** | Observation | Tool not in the observation model |
+| **D** | Domain Completeness | Dependency outside represented domain |
+| **A** | Authority | Tool known but not authorized |
+| **T** | Temporal Freshness | Credential expired |
+| **S** | Semantic Boundary | Resolution mismatch |
+
+Each condition is backed by a deletion-minimality witness proving it independently necessary.
+
+## Session Scope Tracking
+
+Tracks cumulative scope across a session, not just per-call. Individually authorized calls can compose into unauthorized workflows.
+
+    guard.check({"file_read"})       # within credential
+    guard.check({"web_search"})      # outside credential, authorized by policy
+    print(guard.scope())             # shows cumulative drift
+
+## Temporal Freshness
+
+Credentials can expire. DARM Guard detects stale credentials automatically.
+
+    from datetime import datetime, timedelta
+
+    cred = Credential(
+        tools=frozenset(["file_read"]),
+        issued_at=datetime(2026, 9, 1),
+        ttl=timedelta(hours=4),
+    )
+    guard = DARMGuard(policy=p, credential=cred, mode=Mode.GOVERN)
+
+    guard.check({"file_read"}, now=datetime(2026, 9, 1, 2))   # admitted (within TTL)
+    guard.check({"file_read"}, now=datetime(2026, 9, 1, 5))   # rejected (T-failure)
+
+## Credential Escalation
+
+    guard.update_credential({"code_exec"})   # human-approved expansion
+
+## Audit Trail
+
+    import json
+    for entry in guard.audit():
+        print(json.dumps(entry))
+
+## LangChain Integration
+
+    from darm_guard.integrations import guard_tools
+    guarded = guard_tools(agent.tools, guard=my_guard)
+
+## Formal Backing
+
+Every check maps to a Lean 4 theorem in [darm-monitor](https://github.com/Goblohan/darm-monitor):
+
+| Theorem | What it proves | File |
+|---------|---------------|------|
+| target_assured_of_source_and_delta | Conservation: Source + Delta -> Target | R5AssuranceConservation |
+| ag_is_satisfied + causal_safety_fails | O is necessary | E14AGContractComparison |
+| unsupported_authority_substitution | A is necessary | R4bAuthoritySubstitution |
+| temporal_freshness_independently_necessary | T is necessary | E16TemporalFreshness |
+| proposal_authority_separation | Proposal != Authority | E17ProposalAuthoritySeparation |
+| check_true_implies_obligation | Bool check == Prop obligation | E21ExecutableObligationBridge |
+
+167 modules. 31,553 lines. 1,001 theorems. Zero sorry.
+
+## What Makes DARM Guard Different
+
+**Formally verified rejection logic.** Not tested -- proved.
+
+**Session scope tracking.** Cumulative drift, not per-call.
+
+**ODATS diagnostic vocabulary.** Typed diagnoses, not "permission denied."
+
+**Three-mode progressive adoption.** Visibility first, governance when ready.
+
+**Intent-agnostic.** Same structural rejection for benign and malicious agents.
+
+## License
+
+MIT
+
+---
+
+**Olusanya Gbolahan V** -- **PerceptraAI Lab**
+
+[darm-monitor](https://github.com/Goblohan/darm-monitor) | [Darm-Guard](https://github.com/Goblohan/Darm-Guard)

darm_guard-0.1.0/darm_guard.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+darm_guard/__init__.py
+darm_guard/checker.py
+darm_guard/dashboard.py
+darm_guard/guard.py
+darm_guard/session.py
+darm_guard/types.py
+darm_guard.egg-info/PKG-INFO
+darm_guard.egg-info/SOURCES.txt
+darm_guard.egg-info/dependency_links.txt
+darm_guard.egg-info/top_level.txt
+darm_guard/integrations/__init__.py

darm_guard-0.1.0/darm_guard.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

darm_guard-0.1.0/darm_guard.egg-info/top_level.txt

@@ -0,0 +1 @@
+darm_guard

darm_guard-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "darm-guard"
+version = "0.1.0"
+description = "Formally verified agent tool-authorization governance"
+authors = [{name = "Olusanya Gbolahan V"}]
+requires-python = ">=3.9"
+license = {text = "MIT"}
+readme = "README.md"
+keywords = ["ai-safety", "agent-governance", "formal-verification"]
+
+[project.urls]
+"Formal Backing" = "https://github.com/Goblohan/darm-monitor"
+"Source" = "https://github.com/Goblohan/Darm-Guard"
+
+[tool.setuptools.packages.find]
+include = ["darm_guard*"]

darm_guard-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+