handcuff 0.2.0__tar.gz → 0.2.2__tar.gz

{handcuff-0.2.0 → handcuff-0.2.2}/.gitignore

@@ -7,6 +7,7 @@ tests/
 .pytest_cache/
 .ruff_cache/
 .venv/
+.venv310/
 handcuff.spec
 nonexistent.db
 *.db

handcuff-0.2.2/00_README_START_HERE.md

@@ -0,0 +1,33 @@
+# Handcuff — Documentation Index (Start Here)
+
+> **Handcuff** — a dashcam for your AI agents. A local, tamper-evident recorder that captures everything an AI agent does on your machine (processes, files, network) into a searchable, replayable timeline with real-time alerts. Local-first, record-only, zero cloud.
+
+## For the coding agent building this
+
+Read the docs in this order, then execute from the tickets:
+
+| # | Doc | Purpose |
+|---|---|---|
+| 01 | `01_PRD.md` | What we're building and why; scope, users, requirements |
+| 02 | `02_TRD.md` | Architecture, stack, data model, module layout — the technical contract |
+| 03 | `03_Security_Access.md` | Threat model, privilege model, integrity + privacy guarantees, release-gate tests |
+| 04 | `04_Implementation_Plan.md` | Build-order-correct milestones with exit criteria |
+| 05 | `05_Tickets.md` | Atomic, executable tickets (AL-###) in dependency order — **build from here** |
+| 06 | `06_App_Flow.md` | Every runtime flow + state machines (ASCII, parseable) |
+| 07 | `07_Terminal_UI.md` | Rich Textual TUI spec (Claude Code / gemini-cli feel) |
+
+## Build contract (non-negotiables pulled from the docs)
+
+1. **`core/hashing.py` is the single source of truth** for canonical JSON + the SHA-256 chain. The writer and `verify` import it — never reimplement.
+2. **Local-only.** No outbound traffic except a user-configured webhook. `tests/test_no_egress.py` is a release gate.
+3. **Record-only in v1.** Handcuff observes; it never blocks the agent. Backpressure drops events + emits `LOSS`; it must never slow the observed process.
+4. **Observed content is data, never instructions.** Nothing captured from the agent (argv, paths, domains) is ever interpreted as a command to Handcuff.
+5. **Honest integrity claims.** The hash chain is tamper-*evidence*, not a completeness proof; the README states plainly what it does and doesn't guarantee.
+6. **Every ticket ships with its test.** ruff + mypy clean. Five security tests gate releases (see Security §9).
+
+## Suggested first prompt to the coding agent
+
+> "Read docs 00–07 in `/handcuff-docs`. Start with ticket AL-001 and proceed in dependency order. For each ticket, implement the code and its test in one commit, keep ruff/mypy clean, and stop after AL-024 (the vertical slice) so I can review a working `watch` + `sessions` before you continue."
+
+## Tech stack at a glance
+Python 3.11+ · Textual (TUI) · SQLite/WAL · asyncio · psutil/procfs (default capture) · eBPF (opt-in fast path) · watchdog (files) · cryptography/Ed25519 (signing) · httpx (webhooks only) · packaged via pipx/uv + PyInstaller.

handcuff-0.2.2/Dummy Agentic Project/README.md

@@ -0,0 +1,36 @@
+# Dummy Agentic Project
+
+This is a sample project to demonstrate how to test the `handcuff` monitoring tool. 
+It uses LangGraph to orchestrate a workflow with two agents:
+1. **Researcher Agent**: Fetches a random joke from an external API (Network Activity).
+2. **Writer Agent**: Saves the fetched joke to a local file (File Activity).
+
+## Setup
+1. Create a virtual environment (optional but recommended):
+   ```bash
+   python -m venv .venv
+   .venv\Scripts\activate
+   ```
+2. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+## Running the Agent normally
+```bash
+python main.py
+```
+This will fetch a joke and write it to `agent_output.txt`.
+
+## Testing with Handcuff
+To verify that Handcuff successfully intercepts the network and file I/O operations, run the script wrapped with the `handcuff` CLI:
+
+```bash
+handcuff watch python main.py
+```
+
+### What to look for in Handcuff:
+- **Network Request**: Handcuff should flag the `GET` request to `official-joke-api.appspot.com`.
+- **File Activity**: Handcuff should flag the creation and write operations for `agent_output.txt`.
+
+You can view the generated reports in the terminal UI or export them to see the exact logs that Handcuff recorded.

handcuff-0.2.2/Dummy Agentic Project/agent_output.txt

@@ -0,0 +1 @@
+Why do pumpkins sit on people’s porches? - They have no hands to knock on the door.

handcuff-0.2.2/Dummy Agentic Project/main.py

@@ -0,0 +1,71 @@
+import httpx
+from typing import TypedDict
+from langgraph.graph import StateGraph, END
+
+# Define our state
+class AgentState(TypedDict):
+    task: str
+    fetched_data: str
+    output_file: str
+    status: str
+
+# Node 1: The Researcher Agent
+# This agent's job is to fetch data from an external API
+def researcher_agent(state: AgentState):
+    print(f"[Researcher Agent] Fetching data for task: {state['task']}")
+    
+    # Simulating a web search or API call (Network Activity)
+    # We fetch a random joke to have some dynamic content
+    response = httpx.get("https://official-joke-api.appspot.com/random_joke")
+    if response.status_code == 200:
+        data = response.json()
+        joke = f"{data['setup']} - {data['punchline']}"
+    else:
+        joke = "Failed to fetch a joke."
+        
+    print(f"[Researcher Agent] Fetched data: {joke}")
+    
+    return {"fetched_data": joke}
+
+# Node 2: The Writer Agent
+# This agent's job is to save the data to a local file
+def writer_agent(state: AgentState):
+    print(f"[Writer Agent] Writing data to file: {state['output_file']}")
+    
+    # Simulating file modifications (File Activity)
+    with open(state["output_file"], "w", encoding="utf-8") as f:
+        f.write(state["fetched_data"])
+        
+    print("[Writer Agent] Data successfully written.")
+    return {"status": "completed"}
+
+# Build the Graph
+workflow = StateGraph(AgentState)
+
+# Add nodes
+workflow.add_node("researcher", researcher_agent)
+workflow.add_node("writer", writer_agent)
+
+# Add edges (Simple sequential flow)
+workflow.set_entry_point("researcher")
+workflow.add_edge("researcher", "writer")
+workflow.add_edge("writer", END)
+
+# Compile the graph
+app = workflow.compile()
+
+if __name__ == "__main__":
+    print("=== Starting LangGraph Agentic Workflow ===")
+    
+    initial_state = {
+        "task": "Find a joke",
+        "fetched_data": "",
+        "output_file": "agent_output.txt",
+        "status": "pending"
+    }
+    
+    # Run the graph
+    app.invoke(initial_state)
+    
+    print("=== Workflow Completed ===")
+    print("Check 'agent_output.txt' to see the result.")

handcuff-0.2.2/Dummy Agentic Project/requirements.txt

@@ -0,0 +1,5 @@
+langchain
+langgraph
+langchain-community
+httpx
+handcuff

handcuff-0.2.2/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: handcuff
+Version: 0.2.2
+Summary: A dashcam for your AI agents: local, tamper-evident recorder for process/file/network activity, with a LangChain/LangGraph drop-in prompt-injection circuit breaker.
+Project-URL: Homepage, https://github.com/Mister2005/Handcuff
+Project-URL: Repository, https://github.com/Mister2005/Handcuff
+Project-URL: Issues, https://github.com/Mister2005/Handcuff/issues
+Author: Varun Gupta
+License: MIT
+Keywords: agents,langchain,langgraph,observability,prompt-injection,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pillow>=10.0
+Requires-Dist: psutil>=5.9
+Requires-Dist: pyfiglet>=1.0
+Requires-Dist: python-ulid>=2.2
+Requires-Dist: rich-pixels>=3.0
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: textual>=0.58
+Requires-Dist: typer>=0.12
+Requires-Dist: watchdog>=4.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# Handcuff — Documentation Index (Start Here)
+
+> **Handcuff** — a dashcam for your AI agents. A local, tamper-evident recorder that captures everything an AI agent does on your machine (processes, files, network) into a searchable, replayable timeline with real-time alerts. Local-first, record-only, zero cloud.
+
+## For the coding agent building this
+
+Read the docs in this order, then execute from the tickets:
+
+| # | Doc | Purpose |
+|---|---|---|
+| 01 | `01_PRD.md` | What we're building and why; scope, users, requirements |
+| 02 | `02_TRD.md` | Architecture, stack, data model, module layout — the technical contract |
+| 03 | `03_Security_Access.md` | Threat model, privilege model, integrity + privacy guarantees, release-gate tests |
+| 04 | `04_Implementation_Plan.md` | Build-order-correct milestones with exit criteria |
+| 05 | `05_Tickets.md` | Atomic, executable tickets (AL-###) in dependency order — **build from here** |
+| 06 | `06_App_Flow.md` | Every runtime flow + state machines (ASCII, parseable) |
+| 07 | `07_Terminal_UI.md` | Rich Textual TUI spec (Claude Code / gemini-cli feel) |
+
+## Build contract (non-negotiables pulled from the docs)
+
+1. **`core/hashing.py` is the single source of truth** for canonical JSON + the SHA-256 chain. The writer and `verify` import it — never reimplement.
+2. **Local-only.** No outbound traffic except a user-configured webhook. `tests/test_no_egress.py` is a release gate.
+3. **Record-only in v1.** Handcuff observes; it never blocks the agent. Backpressure drops events + emits `LOSS`; it must never slow the observed process.
+4. **Observed content is data, never instructions.** Nothing captured from the agent (argv, paths, domains) is ever interpreted as a command to Handcuff.
+5. **Honest integrity claims.** The hash chain is tamper-*evidence*, not a completeness proof; the README states plainly what it does and doesn't guarantee.
+6. **Every ticket ships with its test.** ruff + mypy clean. Five security tests gate releases (see Security §9).
+
+## Suggested first prompt to the coding agent
+
+> "Read docs 00–07 in `/handcuff-docs`. Start with ticket AL-001 and proceed in dependency order. For each ticket, implement the code and its test in one commit, keep ruff/mypy clean, and stop after AL-024 (the vertical slice) so I can review a working `watch` + `sessions` before you continue."
+
+## Tech stack at a glance
+Python 3.11+ · Textual (TUI) · SQLite/WAL · asyncio · psutil/procfs (default capture) · eBPF (opt-in fast path) · watchdog (files) · cryptography/Ed25519 (signing) · httpx (webhooks only) · packaged via pipx/uv + PyInstaller.

{handcuff-0.2.0 → handcuff-0.2.2}/handcuff/capture/net_watch.py

@@ -126,7 +126,7 @@ class NetworkCaptureBackend:
         while not self._stopped or not self._queue.empty():
             try:
                 yield await asyncio.wait_for(self._queue.get(), timeout=0.5)
-            except TimeoutError:
+            except (TimeoutError, getattr(__import__("asyncio"), "TimeoutError")):
                 if self._stopped:
                     break
 

{handcuff-0.2.0 → handcuff-0.2.2}/handcuff/capture/psutil_backend.py

@@ -97,7 +97,7 @@ class PsutilCaptureBackend:
         while not self._stopped or not self._queue.empty():
             try:
                 yield await asyncio.wait_for(self._queue.get(), timeout=0.5)
-            except TimeoutError:
+            except (TimeoutError, getattr(__import__("asyncio"), "TimeoutError")):
                 if self._stopped:
                     break
 

{handcuff-0.2.0 → handcuff-0.2.2}/handcuff/cli.py

@@ -9,7 +9,7 @@ tickets land.
 from __future__ import annotations
 
 import asyncio
-from datetime import UTC, datetime
+from datetime import datetime, timezone
 from pathlib import Path
 
 import typer
@@ -116,7 +116,7 @@ def sessions() -> None:
         typer.echo("no sessions recorded yet")
         raise typer.Exit()
     for row in rows:
-        started = datetime.fromtimestamp(row["started_at"] / 1000, tz=UTC).isoformat()
+        started = datetime.fromtimestamp(row["started_at"] / 1000, tz=timezone.utc).isoformat()
         typer.echo(
             f"{row['id']}  {row['status']:<24} {started}  {row['label'] or ''}  {row['target_cmd']}"
         )

{handcuff-0.2.0 → handcuff-0.2.2}/handcuff/export/html_export.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 import html
 import json
 import sqlite3
-from datetime import UTC, datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
@@ -38,7 +38,7 @@ th { background: #8882; }
 def _ts(ms: int | None) -> str:
     if not ms:
         return "-"
-    return datetime.fromtimestamp(ms / 1000, tz=UTC).strftime("%Y-%m-%d %H:%M:%S UTC")
+    return datetime.fromtimestamp(ms / 1000, tz=timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
 
 
 def _e(value: Any) -> str:

{handcuff-0.2.0 → handcuff-0.2.2}/handcuff/export/md_export.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 
 import json
 import sqlite3
-from datetime import UTC, datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
@@ -19,7 +19,7 @@ from handcuff.export.json_export import build_export_doc
 def _ts(ms: int | None) -> str:
     if not ms:
         return "-"
-    return datetime.fromtimestamp(ms / 1000, tz=UTC).strftime("%Y-%m-%d %H:%M:%S UTC")
+    return datetime.fromtimestamp(ms / 1000, tz=timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
 
 
 def _md_escape(text: str) -> str:

{handcuff-0.2.0 → handcuff-0.2.2}/handcuff/storage/writer.py

@@ -98,7 +98,7 @@ class StorageWriter:
                 self._append(raw)
                 if len(self._buffer) >= self._batch_size:
                     self.flush()
-            except TimeoutError:
+            except (TimeoutError, getattr(__import__("asyncio"), "TimeoutError")):
                 self.flush()
         self.flush()
 

{handcuff-0.2.0 → handcuff-0.2.2}/handcuff/tui/app.py

@@ -56,6 +56,7 @@ class HandcuffApp(App):
         super().__init__()
         self.db_path = db_path
         self.session_id = session_id
+        self._auto_follow = (session_id is None)
         self.paused = False
         self._last_seq = -1
         self._alert_count = 0
@@ -162,10 +163,24 @@ class HandcuffApp(App):
 
     # --- real data polling ------------------------------------------------
     def poll_updates(self) -> None:
-        if self.paused or self.session_id is None:
+        if self.paused:
             return
         conn = connect(self.db_path)
 
+        if self._auto_follow:
+            row = conn.execute("SELECT id FROM sessions ORDER BY started_at DESC LIMIT 1").fetchone()
+            if row and row["id"] != self.session_id:
+                self.session_id = row["id"]
+                self._last_seq = -1
+                self._alert_count = 0
+                self._event_count = 0
+                self._severities = []
+                self.query_one("#logs", LiveActivity).clear()
+
+        if self.session_id is None:
+            conn.close()
+            return
+
         new_events = conn.execute(
             "SELECT seq, ts, kind, payload_json FROM events "
             "WHERE session_id = ? AND seq > ? ORDER BY seq",

{handcuff-0.2.0 → handcuff-0.2.2}/handcuff/tui/widgets/banner_header.py

@@ -12,7 +12,7 @@ rather than invented to match a mockup that assumed fields we don't have.
 from __future__ import annotations
 
 import time
-from datetime import UTC, datetime
+from datetime import datetime, timezone
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as pkg_version
 
@@ -72,7 +72,7 @@ class SessionInfoBox(Static):
         started_str = "-"
         uptime_str = "00:00:00"
         if self.started_at_ms is not None:
-            started_dt = datetime.fromtimestamp(self.started_at_ms / 1000, tz=UTC)
+            started_dt = datetime.fromtimestamp(self.started_at_ms / 1000, tz=timezone.utc)
             started_str = started_dt.strftime("%Y-%m-%d %H:%M:%S")
             elapsed = max(0, int(time.time() - self.started_at_ms / 1000))
             h, rem = divmod(elapsed, 3600)

{handcuff-0.2.0 → handcuff-0.2.2}/handcuff/tui/widgets/flag_cards.py

@@ -1,63 +1,63 @@
-"""Flagged Events as bordered cards (matches the reference mockup),
-replacing the plain DataTable version — one card per real alert, border
-colored by severity, with a "> View Context" line that really does
-raise a visible detail view (Textual's `notify`) rather than a fake
-inert label.
-"""
-
-from __future__ import annotations
-
-from datetime import UTC, datetime
-
-from rich.text import Text
-from textual.containers import Vertical
-from textual.widgets import Static
-
-_SEVERITY_STYLE = {
-    "critical": ("HIGH", "#FF4D4F"),
-    "warn": ("MEDIUM", "#F1C40F"),
-    "info": ("LOW", "#00D9FF"),
-}
-
-
-class FlagCard(Static):
-    def __init__(self, severity: str, rule_id: str, message: str, ts_ms: int, **kwargs) -> None:
-        super().__init__(**kwargs)
-        self.severity = severity
-        self.rule_id = rule_id
-        self.message = message
-        self.ts_ms = ts_ms
-        label, color = _SEVERITY_STYLE.get(severity, ("LOW", "#8C96A0"))
-        self.styles.border = ("round", color)
-
-    def on_mount(self) -> None:
-        label, color = _SEVERITY_STYLE.get(self.severity, ("LOW", "#8C96A0"))
-        time_str = datetime.fromtimestamp(self.ts_ms / 1000, tz=UTC).strftime("%H:%M:%S")
-
-        text = Text()
-        text.append(f"{self.message}", style=f"bold {color}")
-        text.append(f"  {label}\n", style=f"bold {color}")
-        text.append(f"Rule: {self.rule_id}\n", style="#F4F7FA")
-        text.append(f"Time: {time_str}\n", style="#8C96A0")
-        text.append("> View Context", style="#00D9FF")
-        self.update(text)
-
-    def on_click(self) -> None:
-        self.app.notify(
-            f"rule={self.rule_id}  severity={self.severity}\n{self.message}",
-            title="Flagged event context",
-        )
-
-
-class FlagCards(Vertical):
-    """Container that rebuilds its child FlagCard widgets from a real
-    list of (severity, rule_id, message, ts_ms) tuples each time the
-    underlying alerts change."""
-
-    async def set_alerts(self, alerts: list[tuple[str, str, str, int]]) -> None:
-        await self.remove_children()
-        order = {"critical": 0, "warn": 1, "info": 2}
-        for severity, rule_id, message, ts_ms in sorted(
-            alerts, key=lambda a: order.get(a[0], 3)
-        ):
-            await self.mount(FlagCard(severity, rule_id, message, ts_ms))
+"""Flagged Events as bordered cards (matches the reference mockup),
+replacing the plain DataTable version — one card per real alert, border
+colored by severity, with a "> View Context" line that really does
+raise a visible detail view (Textual's `notify`) rather than a fake
+inert label.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from rich.text import Text
+from textual.containers import Vertical
+from textual.widgets import Static
+
+_SEVERITY_STYLE = {
+    "critical": ("HIGH", "#FF4D4F"),
+    "warn": ("MEDIUM", "#F1C40F"),
+    "info": ("LOW", "#00D9FF"),
+}
+
+
+class FlagCard(Static):
+    def __init__(self, severity: str, rule_id: str, message: str, ts_ms: int, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self.severity = severity
+        self.rule_id = rule_id
+        self.message = message
+        self.ts_ms = ts_ms
+        label, color = _SEVERITY_STYLE.get(severity, ("LOW", "#8C96A0"))
+        self.styles.border = ("round", color)
+
+    def on_mount(self) -> None:
+        label, color = _SEVERITY_STYLE.get(self.severity, ("LOW", "#8C96A0"))
+        time_str = datetime.fromtimestamp(self.ts_ms / 1000, tz=timezone.utc).strftime("%H:%M:%S")
+
+        text = Text()
+        text.append(f"{self.message}", style=f"bold {color}")
+        text.append(f"  {label}\n", style=f"bold {color}")
+        text.append(f"Rule: {self.rule_id}\n", style="#F4F7FA")
+        text.append(f"Time: {time_str}\n", style="#8C96A0")
+        text.append("> View Context", style="#00D9FF")
+        self.update(text)
+
+    def on_click(self) -> None:
+        self.app.notify(
+            f"rule={self.rule_id}  severity={self.severity}\n{self.message}",
+            title="Flagged event context",
+        )
+
+
+class FlagCards(Vertical):
+    """Container that rebuilds its child FlagCard widgets from a real
+    list of (severity, rule_id, message, ts_ms) tuples each time the
+    underlying alerts change."""
+
+    async def set_alerts(self, alerts: list[tuple[str, str, str, int]]) -> None:
+        await self.remove_children()
+        order = {"critical": 0, "warn": 1, "info": 2}
+        for severity, rule_id, message, ts_ms in sorted(
+            alerts, key=lambda a: order.get(a[0], 3)
+        ):
+            await self.mount(FlagCard(severity, rule_id, message, ts_ms))

{handcuff-0.2.0 → handcuff-0.2.2}/handcuff/tui/widgets/logs.py

@@ -6,7 +6,7 @@ table (TIME/LEVEL/ACTION/TARGET/STATUS), driven by real events from the
 from __future__ import annotations
 
 import json
-from datetime import UTC, datetime
+from datetime import datetime, timezone
 
 from textual.widgets import DataTable
 
@@ -56,7 +56,7 @@ class LiveActivity(DataTable):
     def add_event(self, ts_ms: int, kind: str, payload_json: str) -> None:
         payload = json.loads(payload_json) if payload_json else {}
         level = _level_for(kind, payload)
-        time_str = datetime.fromtimestamp(ts_ms / 1000, tz=UTC).strftime("%H:%M:%S")
+        time_str = datetime.fromtimestamp(ts_ms / 1000, tz=timezone.utc).strftime("%H:%M:%S")
         self.add_row(
             time_str,
             level,

{handcuff-0.2.0 → handcuff-0.2.2}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "handcuff"
-version = "0.2.0"
+version = "0.2.2"
 description = "A dashcam for your AI agents: local, tamper-evident recorder for process/file/network activity, with a LangChain/LangGraph drop-in prompt-injection circuit breaker."
-readme = "README.md"
-requires-python = ">=3.11"
+readme = "00_README_START_HERE.md"
+requires-python = ">=3.10"
 license = { text = "MIT" }
 authors = [{ name = "Varun Gupta" }]
 keywords = ["agents", "langchain", "langgraph", "security", "observability", "prompt-injection"]
@@ -13,6 +13,7 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Operating System :: Microsoft :: Windows",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Topic :: Security",
@@ -61,7 +62,7 @@ langchain = [
 
 [tool.ruff]
 line-length = 100
-target-version = "py311"
+target-version = "py310"
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP", "B"]
@@ -70,7 +71,7 @@ select = ["E", "F", "I", "UP", "B"]
 ignore = ["B008", "UP042"]
 
 [tool.mypy]
-python_version = "3.11"
+python_version = "3.10"
 ignore_missing_imports = true
 disallow_untyped_defs = false
 warn_unused_ignores = true

handcuff-0.2.0/PKG-INFO

@@ -1,149 +0,0 @@
-Metadata-Version: 2.4
-Name: handcuff
-Version: 0.2.0
-Summary: A dashcam for your AI agents: local, tamper-evident recorder for process/file/network activity, with a LangChain/LangGraph drop-in prompt-injection circuit breaker.
-Project-URL: Homepage, https://github.com/Mister2005/Handcuff
-Project-URL: Repository, https://github.com/Mister2005/Handcuff
-Project-URL: Issues, https://github.com/Mister2005/Handcuff/issues
-Author: Varun Gupta
-License: MIT
-Keywords: agents,langchain,langgraph,observability,prompt-injection,security
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: Microsoft :: Windows
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Security
-Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.11
-Requires-Dist: cryptography>=42.0
-Requires-Dist: httpx>=0.27
-Requires-Dist: pillow>=10.0
-Requires-Dist: psutil>=5.9
-Requires-Dist: pyfiglet>=1.0
-Requires-Dist: python-ulid>=2.2
-Requires-Dist: rich-pixels>=3.0
-Requires-Dist: ruamel-yaml>=0.18
-Requires-Dist: textual>=0.58
-Requires-Dist: typer>=0.12
-Requires-Dist: watchdog>=4.0
-Provides-Extra: dev
-Requires-Dist: mypy>=1.10; extra == 'dev'
-Requires-Dist: pip-audit>=2.7; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
-Requires-Dist: pytest>=8.2; extra == 'dev'
-Requires-Dist: ruff>=0.5; extra == 'dev'
-Provides-Extra: langchain
-Requires-Dist: langchain-core>=0.2; extra == 'langchain'
-Description-Content-Type: text/markdown
-
-# Handcuff
-
-**A dashcam for your AI agents.** Handcuff records the OS-level side effects of an AI agent — processes spawned, files written, network connections opened — into a local, tamper-evident, hash-chained SQLite timeline you can replay, search, export, and verify. Real-time policy alerts flag risky behavior (sudo, mass deletes, writes outside the workspace, unknown domains, force pushes) while the agent runs.
-
-**Local-only by design:** nothing ever leaves your machine except an optional, user-configured, content-light webhook (HTTPS required). This is enforced by a `test_no_egress` release-gate test.
-
-> **Platform note:** the current implementation targets **Windows** (psutil + watchdog capture, Windows ACL/Firewall enforcement, PyInstaller binary). The original planning docs describe a Linux-first design; that pivot is deliberate. Most capture code is psutil-generic, so Linux/macOS support is feasible but currently untested.
-
-## Install
-
-```powershell
-# From PyPI (Python 3.11+) — note the distribution name; the import
-# name and CLI command are still `handcuff` either way.
-pip install handcuff
-# with the LangChain/LangGraph integration:
-pip install "handcuff[langchain]"
-
-# From source, for development
-pip install .
-
-# Or use the prebuilt binary
-dist\handcuff.exe --help
-```
-
-## Quickstart
-
-```powershell
-# Record an agent (or any command) and everything it does
-handcuff watch -- python my_agent.py
-
-# List recorded sessions, then open the live dashboard
-handcuff sessions
-handcuff tui
-
-# Replay a past session, jumping between alerts
-handcuff replay <SESSION_ID>
-
-# Export a report (json | md | html) and verify its hash chain
-handcuff export <SESSION_ID> --format html
-handcuff verify <SESSION_ID>
-
-# Attach to something already running
-handcuff attach <PID>
-
-# Environment diagnostics
-handcuff doctor
-```
-
-## Key features
-
-- **Tamper-evident timeline** — every event is SHA-256 hash-chained; session heads are Ed25519-signed. `handcuff verify` re-validates the chain from the DB or from a JSON export.
-- **Capture** — process spawn/exit (psutil), file write/delete/rename (watchdog), network connects (psutil). Optional `--hash-content` records a SHA-256 of written files (≤1 MiB; hash only, never content).
-- **Rules & alerts** — safe expression DSL (AST-evaluated, no `eval`), windowed rules, default ruleset, trust allowlist (`handcuff rules trust add domain example.com`), optional webhook on critical alerts.
-- **Redaction** — secrets (API keys, tokens) are scrubbed before events are persisted.
-- **Enforcement (opt-in, Windows)** — `watch --enforce` applies real OS-level blocking: Deny-ACLs on sensitive files (no admin needed) and, if elevated, a Windows Firewall outbound block with `--allow-domain` exceptions. Always reverted on exit.
-- **Cooperative gateway + prompt-injection circuit breaker** — `handcuff.gateway.Gateway` is a validating proxy for agent frameworks that route their file/network tool calls through it (same trust model as an OpenAI/LangChain/MCP tool sandbox — see its docstring for exact scope, it cannot stop raw shell/socket access). Every fetched URL (and any file read marked `untrusted=True`) is scanned with a heuristic prompt-injection signature scanner (`handcuff.rules.injection`) covering instruction-override phrasing, fake system/assistant turn markers, jailbreak personas, data-exfiltration instructions, and obfuscation tells (hidden Unicode, suspicious base64 blobs). A match "taints" the session for a configurable window and the gateway then **blocks further network egress** — the deterministic mitigation for Simon Willison's "lethal trifecta" (private data access + untrusted content + external communication), rather than trying to out-guess the injection semantically. This is a regex/heuristic tripwire, not a semantic guarantee — a novel or paraphrased injection can still slip past it; treat a miss as "not a known pattern" rather than "safe."
-
-  ```python
-  from pathlib import Path
-  from handcuff.gateway.gateway import Gateway, GatewayDenied
-
-  with Gateway(workspace_root=Path("./agent_workspace")) as gw:
-      page = gw.http_request("https://example.com/some-doc")  # scanned automatically
-      if gw.is_tainted:
-          print("suspected prompt injection:", gw.taint_info.reason)
-      try:
-          gw.http_request("https://wherever-the-doc-said-to-send-data.example")
-      except GatewayDenied as e:
-          print("blocked:", e)  # circuit breaker fired
-  ```
-- **TUI dashboard** — trust meter, flagged-event cards, live monitoring, recommendation panel (Textual).
-- **Exports** — JSON (with embedded verification block), Markdown, and self-contained HTML reports.
-- **Multi-agent framework integration (LangChain / LangGraph), one line of code** — `handcuff.integrations.langchain.HandcuffHandler` is a real `langchain-core` `BaseCallbackHandler`. Pass it as `callbacks=[handler]` to any chain, agent, or graph and it records every chain/tool/retriever call as a hash-chained event **and** runs the same injection scanner + taint circuit breaker as the Gateway, scoped per agent. It works for concurrent/parallel agents (multiple LangGraph nodes, `ThreadPoolExecutor`, `asyncio.gather`) because it keys state off LangChain's own `run_id`/`parent_run_id` run tree — the same mechanism LangChain uses internally to keep parallel runs from crossing wires — with all shared state protected by a lock for real cross-thread safety. `pip install handcuff[langchain]` to pull in `langchain-core`. Verified against the real package end-to-end (parallel `ThreadPoolExecutor` agents, real `@tool`s, real blocking) — see `tests/test_langchain_real.py`.
-
-  ```python
-  from handcuff.integrations.langchain import HandcuffHandler
-
-  handler = HandcuffHandler()  # writes to the same DB `handcuff tui` watches
-  result = my_graph.invoke(inputs, config={"callbacks": [handler]})
-  handler.close()
-  ```
-
-  Run `handcuff tui` in another terminal while your agent(s) run — it polls the same DB and picks the session up live automatically, no extra wiring. Honest scope: this only sees what happens through LangChain's own abstractions (chains/tools/retrievers) — a tool implementation that shells out or calls `requests` directly with no LangChain wrapper around it never fires these callbacks, and taint is scoped to one run tree (one top-level `.invoke()`), not the whole process.
-
-## Configuration
-
-```powershell
-handcuff config list
-handcuff config set retention_days 14
-handcuff config set webhook_url https://hooks.example.com/handcuff
-```
-
-Config lives at `~/.config/handcuff/config.yaml`; the DB at `~/.local/share/handcuff/handcuff.db`; the signing key at `~/.config/handcuff/ed25519.key`.
-
-## Development
-
-```powershell
-python -m venv .venv && .venv\Scripts\pip install -e .[dev,langchain]
-.venv\Scripts\python -m pytest tests -q     # ~180 tests
-.venv\Scripts\ruff check handcuff tests
-scripts\build_windows.ps1                    # PyInstaller binary
-```
-
-Security release gates (must always pass): no-egress, chain-tamper detection, redaction, DSL safety, watchdog reconcile.
-
-## Documentation
-
-Planning and design docs live in the repo root: [PRD](01_PRD.md), [TRD](02_TRD.md), [Security](03_Security_Access.md), [Implementation Plan](04_Implementation_Plan.md), [Tickets](05_Tickets.md), and the TUI spec (`Handcuff_SPEC_Part1-4.md`).