actgate 0.1.0__tar.gz

actgate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tymur Kartsan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

actgate-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: actgate
+Version: 0.1.0
+Summary: Local intent ledger and approval gate for tool actions
+License-Expression: MIT
+Project-URL: Repository, https://github.com/kartsan03/actgate
+Project-URL: Issues, https://github.com/kartsan03/actgate/issues
+Project-URL: Changelog, https://github.com/kartsan03/actgate/blob/main/CHANGELOG.md
+Keywords: intent,ledger,approval,agent,cli,security,audit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+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 :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# ActGate
+
+[![ci](https://github.com/kartsan03/actgate/actions/workflows/ci.yml/badge.svg)](https://github.com/kartsan03/actgate/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Local IntentLedger: propose a tool action, record approve or deny in an
+append-only hash-chained ledger, verify the chain before you trust it.
+
+This is not an MCP proxy yet. This is not a SaaS. Everything runs offline
+against files on disk.
+
+dry-run and approve record decisions only; they do not execute tools.
+
+## Install
+
+```
+pip install -e .[dev]
+```
+
+## Quickstart
+
+```
+actgate init
+actgate propose --tool shell.exec --args '{"cmd":"ls"}' --blast-tags fs.read
+actgate dry-run <intent_id>
+actgate approve <intent_id>
+actgate verify
+actgate list
+```
+
+Deny path:
+
+```
+actgate deny <intent_id> --reason "too broad"
+# exits 1
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | ok (propose, approve, verify clean, show/list) |
+| 1 | deny recorded, or verify found a broken chain / bad seal |
+| 2 | setup error (missing ledger, bad path, invalid args) |
+
+## Intent shape
+
+```json
+{
+  "tool": "shell.exec",
+  "args": {"cmd": "ls"},
+  "args_hash": null,
+  "blast_tags": ["fs.read"],
+  "requested_mode": "execute",
+  "created_at": "2026-09-06T00:00:00+00:00"
+}
+```
+
+Provide either `args` or `args_hash` (sha256 of canonical JSON args). Optional
+`blast_tags` and `requested_mode`.
+
+## Ledger
+
+`.actgate/ledger.jsonl` is append-only. Each line has `prev_hash` / `entry_hash`
+(sha256). Bare `verify` checks chain integrity only: a rewritten but
+internally consistent chain still passes. It is not a signature check unless
+you opt in.
+
+Optional authenticity: set `ACTGATE_SEAL_KEY` when writing so entries get an
+HMAC seal. Then `verify` (with the key set) requires matching seals, or pass
+`verify --require-seal` to fail when seals are missing.
+
+Path escapes outside the ledger root are rejected (exit 2).
+
+## What this is not
+
+- Not an MCP proxy (yet)
+- Not a hosted approval product
+- No network calls in the core path
+
+## Development
+
+```
+pip install -e .[dev]
+pytest
+```

actgate-0.1.0/README.md

@@ -0,0 +1,87 @@
+# ActGate
+
+[![ci](https://github.com/kartsan03/actgate/actions/workflows/ci.yml/badge.svg)](https://github.com/kartsan03/actgate/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Local IntentLedger: propose a tool action, record approve or deny in an
+append-only hash-chained ledger, verify the chain before you trust it.
+
+This is not an MCP proxy yet. This is not a SaaS. Everything runs offline
+against files on disk.
+
+dry-run and approve record decisions only; they do not execute tools.
+
+## Install
+
+```
+pip install -e .[dev]
+```
+
+## Quickstart
+
+```
+actgate init
+actgate propose --tool shell.exec --args '{"cmd":"ls"}' --blast-tags fs.read
+actgate dry-run <intent_id>
+actgate approve <intent_id>
+actgate verify
+actgate list
+```
+
+Deny path:
+
+```
+actgate deny <intent_id> --reason "too broad"
+# exits 1
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | ok (propose, approve, verify clean, show/list) |
+| 1 | deny recorded, or verify found a broken chain / bad seal |
+| 2 | setup error (missing ledger, bad path, invalid args) |
+
+## Intent shape
+
+```json
+{
+  "tool": "shell.exec",
+  "args": {"cmd": "ls"},
+  "args_hash": null,
+  "blast_tags": ["fs.read"],
+  "requested_mode": "execute",
+  "created_at": "2026-09-06T00:00:00+00:00"
+}
+```
+
+Provide either `args` or `args_hash` (sha256 of canonical JSON args). Optional
+`blast_tags` and `requested_mode`.
+
+## Ledger
+
+`.actgate/ledger.jsonl` is append-only. Each line has `prev_hash` / `entry_hash`
+(sha256). Bare `verify` checks chain integrity only: a rewritten but
+internally consistent chain still passes. It is not a signature check unless
+you opt in.
+
+Optional authenticity: set `ACTGATE_SEAL_KEY` when writing so entries get an
+HMAC seal. Then `verify` (with the key set) requires matching seals, or pass
+`verify --require-seal` to fail when seals are missing.
+
+Path escapes outside the ledger root are rejected (exit 2).
+
+## What this is not
+
+- Not an MCP proxy (yet)
+- Not a hosted approval product
+- No network calls in the core path
+
+## Development
+
+```
+pip install -e .[dev]
+pytest
+```

actgate-0.1.0/actgate/__init__.py

@@ -0,0 +1,3 @@
+"""ActGate: local IntentLedger for tool-action propose / approve / deny."""
+
+__version__ = "0.1.0"

actgate-0.1.0/actgate/__main__.py

@@ -0,0 +1,3 @@
+from actgate.cli import main
+
+raise SystemExit(main())

actgate-0.1.0/actgate/cli.py

@@ -0,0 +1,268 @@
+"""ActGate CLI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from actgate import __version__
+from actgate.core.intent import Intent, IntentError, build_intent
+from actgate.core.ledger import Ledger, LedgerError, resolve_ledger_path
+from actgate.core.verify import verify_ledger
+
+
+def _eprint(msg: str) -> None:
+    print(msg, file=sys.stderr)
+
+
+def _ledger_from_args(args: argparse.Namespace) -> Ledger:
+    root = Path(args.root).resolve() if getattr(args, "root", None) else Path.cwd()
+    path = getattr(args, "ledger", None)
+    return Ledger.open(root=root, path=path)
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    target = Path(args.directory).resolve() if args.directory else Path.cwd()
+    ledger = Ledger.open(root=target)
+    ledger.ensure()
+    print(f"initialized {ledger.path}")
+    return 0
+
+
+def _parse_args_json(raw: str | None) -> dict[str, Any] | None:
+    if raw is None:
+        return None
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise IntentError(f"invalid --args JSON: {exc}") from exc
+    if not isinstance(data, dict):
+        raise IntentError("--args must be a JSON object")
+    return data
+
+
+def cmd_propose(args: argparse.Namespace) -> int:
+    try:
+        intent = build_intent(
+            tool=args.tool,
+            args=_parse_args_json(args.args),
+            args_hash=args.args_hash,
+            blast_tags=[t for t in (args.blast_tags or "").split(",") if t],
+            requested_mode=args.mode,
+        )
+        ledger = _ledger_from_args(args)
+        if not ledger.exists():
+            ledger.ensure()
+        entry = ledger.append("propose", intent=intent)
+    except (IntentError, LedgerError) as exc:
+        _eprint(str(exc))
+        return 2
+    print(json.dumps({"intent_id": intent.id, "entry_hash": entry["entry_hash"]}, indent=2))
+    return 0
+
+
+def cmd_dry_run(args: argparse.Namespace) -> int:
+    try:
+        ledger = _ledger_from_args(args)
+        if not ledger.exists():
+            raise LedgerError(f"ledger not found: {ledger.path}")
+        proposal = ledger.get_proposal(args.intent_id)
+        if proposal is None:
+            raise LedgerError(f"no propose event for intent_id={args.intent_id}")
+        decision = ledger.latest_decision(args.intent_id)
+    except LedgerError as exc:
+        _eprint(str(exc))
+        return 2
+    out = {
+        "intent_id": args.intent_id,
+        "intent": proposal.get("intent"),
+        "decision": None if decision is None else decision.get("action"),
+        "would_execute": decision is not None and decision.get("action") == "approve",
+    }
+    print(json.dumps(out, indent=2))
+    return 0
+
+
+def cmd_approve(args: argparse.Namespace) -> int:
+    try:
+        ledger = _ledger_from_args(args)
+        if not ledger.exists():
+            raise LedgerError(f"ledger not found: {ledger.path}")
+        proposal = ledger.get_proposal(args.intent_id)
+        if proposal is None:
+            raise LedgerError(f"no propose event for intent_id={args.intent_id}")
+        intent = Intent.from_dict(proposal["intent"])
+        existing = ledger.latest_decision(args.intent_id)
+        if existing is not None:
+            raise LedgerError(
+                f"intent already decided: {existing.get('action')} ({existing.get('entry_hash')})"
+            )
+        entry = ledger.append(
+            "approve",
+            intent=intent,
+            decision="approved",
+            reason=args.reason,
+        )
+    except (IntentError, LedgerError) as exc:
+        _eprint(str(exc))
+        return 2
+    print(json.dumps({"intent_id": intent.id, "action": "approve", "entry_hash": entry["entry_hash"]}, indent=2))
+    return 0
+
+
+def cmd_deny(args: argparse.Namespace) -> int:
+    try:
+        ledger = _ledger_from_args(args)
+        if not ledger.exists():
+            raise LedgerError(f"ledger not found: {ledger.path}")
+        proposal = ledger.get_proposal(args.intent_id)
+        if proposal is None:
+            raise LedgerError(f"no propose event for intent_id={args.intent_id}")
+        intent = Intent.from_dict(proposal["intent"])
+        existing = ledger.latest_decision(args.intent_id)
+        if existing is not None:
+            raise LedgerError(
+                f"intent already decided: {existing.get('action')} ({existing.get('entry_hash')})"
+            )
+        entry = ledger.append(
+            "deny",
+            intent=intent,
+            decision="denied",
+            reason=args.reason or "denied",
+        )
+    except (IntentError, LedgerError) as exc:
+        _eprint(str(exc))
+        return 2
+    print(json.dumps({"intent_id": intent.id, "action": "deny", "entry_hash": entry["entry_hash"]}, indent=2))
+    return 1
+
+
+def cmd_verify(args: argparse.Namespace) -> int:
+    try:
+        ledger = _ledger_from_args(args)
+        if not ledger.exists():
+            raise LedgerError(f"ledger not found: {ledger.path}")
+        result = verify_ledger(
+            ledger, require_seal=True if getattr(args, "require_seal", False) else None
+        )
+    except LedgerError as exc:
+        _eprint(str(exc))
+        return 2
+    if result.ok:
+        print(json.dumps({"ok": True, "entries": result.entries}, indent=2))
+        return 0
+    _eprint("verify failed:")
+    for err in result.errors:
+        _eprint(f"  - {err}")
+    return 1
+
+
+def cmd_show(args: argparse.Namespace) -> int:
+    try:
+        ledger = _ledger_from_args(args)
+        if not ledger.exists():
+            raise LedgerError(f"ledger not found: {ledger.path}")
+        events = ledger.find_intent_events(args.intent_id)
+        if not events:
+            raise LedgerError(f"unknown intent_id={args.intent_id}")
+    except LedgerError as exc:
+        _eprint(str(exc))
+        return 2
+    print(json.dumps({"intent_id": args.intent_id, "events": events}, indent=2))
+    return 0
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    try:
+        ledger = _ledger_from_args(args)
+        if not ledger.exists():
+            raise LedgerError(f"ledger not found: {ledger.path}")
+        seen: dict[str, dict[str, Any]] = {}
+        for entry in ledger.read_entries():
+            iid = entry.get("intent_id")
+            if not iid:
+                continue
+            row = seen.setdefault(
+                iid,
+                {"intent_id": iid, "tool": None, "status": "proposed", "seq": entry["seq"]},
+            )
+            if entry.get("action") == "propose":
+                intent = entry.get("intent") or {}
+                row["tool"] = intent.get("tool")
+                row["seq"] = entry["seq"]
+            elif entry.get("action") in ("approve", "deny"):
+                row["status"] = "approved" if entry["action"] == "approve" else "denied"
+    except LedgerError as exc:
+        _eprint(str(exc))
+        return 2
+    rows = sorted(seen.values(), key=lambda r: r["seq"])
+    print(json.dumps(rows, indent=2))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="actgate",
+        description="Local IntentLedger: propose, approve, deny, verify tool intents.",
+    )
+    parser.add_argument("--version", action="version", version=f"actgate {__version__}")
+    parser.add_argument("--root", default=None, help="project root containing .actgate/")
+    parser.add_argument("--ledger", default=None, help="explicit ledger.jsonl path (must stay under root)")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_init = sub.add_parser("init", help="create .actgate/ledger.jsonl")
+    p_init.add_argument("directory", nargs="?", default=None)
+    p_init.set_defaults(func=cmd_init)
+
+    p_prop = sub.add_parser("propose", help="append a propose event")
+    p_prop.add_argument("--tool", required=True)
+    p_prop.add_argument("--args", default=None, help="JSON object of tool args")
+    p_prop.add_argument("--args-hash", dest="args_hash", default=None)
+    p_prop.add_argument("--blast-tags", dest="blast_tags", default="", help="comma-separated tags")
+    p_prop.add_argument("--mode", dest="mode", default="execute", help="requested_mode")
+    p_prop.set_defaults(func=cmd_propose)
+
+    p_dry = sub.add_parser("dry-run", help="show intent and whether it would execute")
+    p_dry.add_argument("intent_id")
+    p_dry.set_defaults(func=cmd_dry_run)
+
+    p_ok = sub.add_parser("approve", help="append an approve event")
+    p_ok.add_argument("intent_id")
+    p_ok.add_argument("--reason", default=None)
+    p_ok.set_defaults(func=cmd_approve)
+
+    p_no = sub.add_parser("deny", help="append a deny event (exit 1)")
+    p_no.add_argument("intent_id")
+    p_no.add_argument("--reason", default=None)
+    p_no.set_defaults(func=cmd_deny)
+
+    p_ver = sub.add_parser("verify", help="verify ledger hash chain (exit 0/1/2)")
+    p_ver.add_argument(
+        "--require-seal",
+        action="store_true",
+        help="fail if entries lack HMAC seals (use with ACTGATE_SEAL_KEY)",
+    )
+    p_ver.set_defaults(func=cmd_verify)
+
+    p_show = sub.add_parser("show", help="show events for an intent")
+    p_show.add_argument("intent_id")
+    p_show.set_defaults(func=cmd_show)
+
+    p_list = sub.add_parser("list", help="list intents and status")
+    p_list.set_defaults(func=cmd_list)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except LedgerError as exc:
+        _eprint(str(exc))
+        return 2

actgate-0.1.0/actgate/core/__init__.py

@@ -0,0 +1,17 @@
+"""Core IntentLedger pieces: intent, ledger, verify."""
+
+from actgate.core.intent import Intent, IntentError, build_intent, hash_args
+from actgate.core.ledger import Ledger, LedgerError, resolve_ledger_path
+from actgate.core.verify import VerifyResult, verify_ledger
+
+__all__ = [
+    "Intent",
+    "IntentError",
+    "build_intent",
+    "hash_args",
+    "Ledger",
+    "LedgerError",
+    "resolve_ledger_path",
+    "VerifyResult",
+    "verify_ledger",
+]

actgate-0.1.0/actgate/core/intent.py

@@ -0,0 +1,83 @@
+"""Intent model: tool action proposals."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+class IntentError(ValueError):
+    """Invalid intent input (setup error)."""
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def canonical_json(obj: Any) -> str:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def hash_args(args: Any) -> str:
+    return hashlib.sha256(canonical_json(args).encode("utf-8")).hexdigest()
+
+
+@dataclass
+class Intent:
+    tool: str
+    created_at: str
+    id: str = field(default_factory=lambda: uuid.uuid4().hex)
+    args: dict[str, Any] | None = None
+    args_hash: str | None = None
+    blast_tags: list[str] = field(default_factory=list)
+    requested_mode: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Intent":
+        return cls(
+            id=data["id"],
+            tool=data["tool"],
+            created_at=data["created_at"],
+            args=data.get("args"),
+            args_hash=data.get("args_hash"),
+            blast_tags=list(data.get("blast_tags") or []),
+            requested_mode=data.get("requested_mode"),
+        )
+
+
+def build_intent(
+    tool: str,
+    args: dict[str, Any] | None = None,
+    args_hash: str | None = None,
+    blast_tags: list[str] | None = None,
+    requested_mode: str | None = None,
+    created_at: str | None = None,
+    intent_id: str | None = None,
+) -> Intent:
+    tool = (tool or "").strip()
+    if not tool:
+        raise IntentError("tool is required")
+    if args is None and not args_hash:
+        raise IntentError("provide args or args_hash")
+    if args is not None and args_hash:
+        computed = hash_args(args)
+        if computed != args_hash:
+            raise IntentError("args_hash does not match args")
+    if args is not None and not args_hash:
+        args_hash = hash_args(args)
+    return Intent(
+        id=intent_id or uuid.uuid4().hex,
+        tool=tool,
+        args=args,
+        args_hash=args_hash,
+        blast_tags=list(blast_tags or []),
+        requested_mode=requested_mode,
+        created_at=created_at or _utc_now(),
+    )

actgate-0.1.0/actgate/core/ledger.py

@@ -0,0 +1,151 @@
+"""Append-only sha256-chained ledger.jsonl."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterator
+
+from actgate.core.intent import Intent, canonical_json
+
+
+GENESIS = "0" * 64
+LEDGER_DIR = ".actgate"
+LEDGER_NAME = "ledger.jsonl"
+
+
+class LedgerError(ValueError):
+    """Ledger path or I/O setup error."""
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def resolve_ledger_path(
+    root: Path | str | None = None, path: Path | str | None = None
+) -> Path:
+    """Resolve ledger file path; reject escapes outside the chosen root."""
+    base = Path(root).resolve() if root else Path.cwd().resolve()
+    if path is not None:
+        candidate = Path(path).expanduser()
+        if not candidate.is_absolute():
+            candidate = (base / candidate).resolve()
+        else:
+            candidate = candidate.resolve()
+        try:
+            candidate.relative_to(base)
+        except ValueError as exc:
+            raise LedgerError(f"path escapes ledger root: {candidate}") from exc
+        return candidate
+    return (base / LEDGER_DIR / LEDGER_NAME).resolve()
+
+
+def seal_key() -> bytes | None:
+    raw = os.environ.get("ACTGATE_SEAL_KEY")
+    if not raw:
+        return None
+    return raw.encode("utf-8")
+
+
+def entry_payload_for_hash(entry: dict[str, Any]) -> str:
+    """Canonical payload excluding entry_hash and seal."""
+    payload = {k: v for k, v in entry.items() if k not in ("entry_hash", "seal")}
+    return canonical_json(payload)
+
+
+def compute_entry_hash(entry: dict[str, Any]) -> str:
+    return hashlib.sha256(entry_payload_for_hash(entry).encode("utf-8")).hexdigest()
+
+
+def compute_seal(entry_hash: str, key: bytes) -> str:
+    return hmac.new(key, entry_hash.encode("utf-8"), hashlib.sha256).hexdigest()
+
+
+@dataclass
+class Ledger:
+    path: Path
+
+    @classmethod
+    def open(
+        cls, root: Path | str | None = None, path: Path | str | None = None
+    ) -> "Ledger":
+        return cls(path=resolve_ledger_path(root=root, path=path))
+
+    def ensure(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        if not self.path.exists():
+            self.path.touch()
+
+    def exists(self) -> bool:
+        return self.path.is_file()
+
+    def read_entries(self) -> list[dict[str, Any]]:
+        if not self.exists():
+            return []
+        entries: list[dict[str, Any]] = []
+        text = self.path.read_text(encoding="utf-8")
+        for line_no, line in enumerate(text.splitlines(), start=1):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entries.append(json.loads(line))
+            except json.JSONDecodeError as exc:
+                raise LedgerError(f"malformed ledger line {line_no}: {exc}") from exc
+        return entries
+
+    def iter_entries(self) -> Iterator[dict[str, Any]]:
+        yield from self.read_entries()
+
+    def last_hash(self) -> str:
+        entries = self.read_entries()
+        if not entries:
+            return GENESIS
+        return entries[-1]["entry_hash"]
+
+    def append(
+        self, action: str, intent: Intent | None = None, **extra: Any
+    ) -> dict[str, Any]:
+        self.ensure()
+        entries = self.read_entries()
+        seq = (entries[-1]["seq"] + 1) if entries else 1
+        prev_hash = entries[-1]["entry_hash"] if entries else GENESIS
+        entry: dict[str, Any] = {
+            "seq": seq,
+            "prev_hash": prev_hash,
+            "action": action,
+            "ts": _utc_now(),
+        }
+        if intent is not None:
+            entry["intent_id"] = intent.id
+            entry["intent"] = intent.to_dict()
+        entry.update(extra)
+        entry["entry_hash"] = compute_entry_hash(entry)
+        key = seal_key()
+        if key is not None:
+            entry["seal"] = compute_seal(entry["entry_hash"], key)
+        with self.path.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(entry, ensure_ascii=False, sort_keys=True) + chr(10))
+        return entry
+
+    def find_intent_events(self, intent_id: str) -> list[dict[str, Any]]:
+        return [e for e in self.read_entries() if e.get("intent_id") == intent_id]
+
+    def latest_decision(self, intent_id: str) -> dict[str, Any] | None:
+        events = self.find_intent_events(intent_id)
+        for event in reversed(events):
+            if event.get("action") in ("approve", "deny"):
+                return event
+        return None
+
+    def get_proposal(self, intent_id: str) -> dict[str, Any] | None:
+        for event in self.find_intent_events(intent_id):
+            if event.get("action") == "propose":
+                return event
+        return None

actgate-0.1.0/actgate/core/verify.py

@@ -0,0 +1,71 @@
+"""Ledger chain verification."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from actgate.core.ledger import (
+    GENESIS,
+    LedgerError,
+    Ledger,
+    compute_entry_hash,
+    compute_seal,
+    seal_key,
+)
+
+
+@dataclass
+class VerifyResult:
+    ok: bool
+    errors: list[str] = field(default_factory=list)
+    entries: int = 0
+
+    @property
+    def exit_code(self) -> int:
+        return 0 if self.ok else 1
+
+
+def verify_ledger(ledger: Ledger, require_seal: bool | None = None) -> VerifyResult:
+    """Verify hash chain and optional HMAC seals.
+
+    Returns ok=False (exit 1) on broken chain or bad/missing seal when required.
+    """
+    errors: list[str] = []
+    try:
+        entries = ledger.read_entries()
+    except LedgerError as exc:
+        return VerifyResult(ok=False, errors=[str(exc)])
+
+    key = seal_key()
+    if require_seal is None:
+        require_seal = key is not None
+
+    prev = GENESIS
+    for i, entry in enumerate(entries):
+        seq = entry.get("seq")
+        if seq != i + 1:
+            errors.append(f"seq mismatch at index {i}: expected {i + 1}, got {seq}")
+        if entry.get("prev_hash") != prev:
+            errors.append(
+                f"prev_hash mismatch at seq {seq}: expected {prev}, got {entry.get('prev_hash')}"
+            )
+        expected_hash = compute_entry_hash(entry)
+        if entry.get("entry_hash") != expected_hash:
+            errors.append(
+                f"entry_hash mismatch at seq {seq}: expected {expected_hash}, got {entry.get('entry_hash')}"
+            )
+        if require_seal:
+            if key is None:
+                errors.append(f"seal required but ACTGATE_SEAL_KEY unset at seq {seq}")
+            else:
+                seal = entry.get("seal")
+                if not seal:
+                    errors.append(f"missing seal at seq {seq}")
+                else:
+                    expected_seal = compute_seal(entry["entry_hash"], key)
+                    if not (seal == expected_seal):
+                        errors.append(f"bad seal at seq {seq}")
+        prev = entry.get("entry_hash", "")
+
+    return VerifyResult(ok=not errors, errors=errors, entries=len(entries))

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

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: actgate
+Version: 0.1.0
+Summary: Local intent ledger and approval gate for tool actions
+License-Expression: MIT
+Project-URL: Repository, https://github.com/kartsan03/actgate
+Project-URL: Issues, https://github.com/kartsan03/actgate/issues
+Project-URL: Changelog, https://github.com/kartsan03/actgate/blob/main/CHANGELOG.md
+Keywords: intent,ledger,approval,agent,cli,security,audit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+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 :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# ActGate
+
+[![ci](https://github.com/kartsan03/actgate/actions/workflows/ci.yml/badge.svg)](https://github.com/kartsan03/actgate/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Local IntentLedger: propose a tool action, record approve or deny in an
+append-only hash-chained ledger, verify the chain before you trust it.
+
+This is not an MCP proxy yet. This is not a SaaS. Everything runs offline
+against files on disk.
+
+dry-run and approve record decisions only; they do not execute tools.
+
+## Install
+
+```
+pip install -e .[dev]
+```
+
+## Quickstart
+
+```
+actgate init
+actgate propose --tool shell.exec --args '{"cmd":"ls"}' --blast-tags fs.read
+actgate dry-run <intent_id>
+actgate approve <intent_id>
+actgate verify
+actgate list
+```
+
+Deny path:
+
+```
+actgate deny <intent_id> --reason "too broad"
+# exits 1
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | ok (propose, approve, verify clean, show/list) |
+| 1 | deny recorded, or verify found a broken chain / bad seal |
+| 2 | setup error (missing ledger, bad path, invalid args) |
+
+## Intent shape
+
+```json
+{
+  "tool": "shell.exec",
+  "args": {"cmd": "ls"},
+  "args_hash": null,
+  "blast_tags": ["fs.read"],
+  "requested_mode": "execute",
+  "created_at": "2026-09-06T00:00:00+00:00"
+}
+```
+
+Provide either `args` or `args_hash` (sha256 of canonical JSON args). Optional
+`blast_tags` and `requested_mode`.
+
+## Ledger
+
+`.actgate/ledger.jsonl` is append-only. Each line has `prev_hash` / `entry_hash`
+(sha256). Bare `verify` checks chain integrity only: a rewritten but
+internally consistent chain still passes. It is not a signature check unless
+you opt in.
+
+Optional authenticity: set `ACTGATE_SEAL_KEY` when writing so entries get an
+HMAC seal. Then `verify` (with the key set) requires matching seals, or pass
+`verify --require-seal` to fail when seals are missing.
+
+Path escapes outside the ledger root are rejected (exit 2).
+
+## What this is not
+
+- Not an MCP proxy (yet)
+- Not a hosted approval product
+- No network calls in the core path
+
+## Development
+
+```
+pip install -e .[dev]
+pytest
+```

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

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+actgate/__init__.py
+actgate/__main__.py
+actgate/cli.py
+actgate.egg-info/PKG-INFO
+actgate.egg-info/SOURCES.txt
+actgate.egg-info/dependency_links.txt
+actgate.egg-info/entry_points.txt
+actgate.egg-info/requires.txt
+actgate.egg-info/top_level.txt
+actgate/core/__init__.py
+actgate/core/intent.py
+actgate/core/ledger.py
+actgate/core/verify.py
+tests/test_actgate.py

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

@@ -0,0 +1 @@
+

actgate-0.1.0/actgate.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+actgate = actgate.cli:main

actgate-0.1.0/actgate.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=8

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

@@ -0,0 +1 @@
+actgate

actgate-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "actgate"
+version = "0.1.0"
+description = "Local intent ledger and approval gate for tool actions"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["intent", "ledger", "approval", "agent", "cli", "security", "audit"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/kartsan03/actgate"
+Issues = "https://github.com/kartsan03/actgate/issues"
+Changelog = "https://github.com/kartsan03/actgate/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+actgate = "actgate.cli:main"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["actgate*"]

actgate-0.1.0/setup.cfg

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

actgate-0.1.0/tests/test_actgate.py

@@ -0,0 +1,151 @@
+"""ActGate MVP tests: propose/approve/deny/verify/path escapes."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import pytest
+
+from actgate.cli import main
+from actgate.core.intent import IntentError, build_intent, hash_args
+from actgate.core.ledger import GENESIS, Ledger, LedgerError, resolve_ledger_path
+from actgate.core.verify import verify_ledger
+
+
+@pytest.fixture
+def root(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.delenv("ACTGATE_SEAL_KEY", raising=False)
+    assert main(["init"]) == 0
+    return tmp_path
+
+
+def test_propose_approve_verify(root: Path) -> None:
+    rc = main(["propose", "--tool", "shell.exec", "--args", '{"cmd":"ls"}', "--blast-tags", "fs.read"])
+    assert rc == 0
+    ledger = Ledger.open(root=root)
+    proposal = [e for e in ledger.read_entries() if e["action"] == "propose"][0]
+    iid = proposal["intent_id"]
+    assert main(["dry-run", iid]) == 0
+    assert main(["approve", iid]) == 0
+    assert main(["verify"]) == 0
+    assert main(["show", iid]) == 0
+    assert main(["list"]) == 0
+    entries = ledger.read_entries()
+    assert entries[0]["prev_hash"] == GENESIS
+    assert entries[1]["prev_hash"] == entries[0]["entry_hash"]
+
+
+def test_deny_exits_one(root: Path) -> None:
+    assert main(["propose", "--tool", "fs.write", "--args", '{"path":"/tmp/x"}']) == 0
+    iid = Ledger.open(root=root).read_entries()[0]["intent_id"]
+    assert main(["deny", iid, "--reason", "too broad"]) == 1
+    assert main(["verify"]) == 0
+    decision = Ledger.open(root=root).latest_decision(iid)
+    assert decision is not None
+    assert decision["action"] == "deny"
+
+
+def test_broken_chain_verify_fails(root: Path) -> None:
+    assert main(["propose", "--tool", "t", "--args", "{}"]) == 0
+    ledger = Ledger.open(root=root)
+    path = ledger.path
+    lines = path.read_text().splitlines()
+    entry = json.loads(lines[0])
+    entry["entry_hash"] = "deadbeef" * 8
+    path.write_text(json.dumps(entry, sort_keys=True) + "\n")
+    assert main(["verify"]) == 1
+
+
+def test_hmac_seal(root: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("ACTGATE_SEAL_KEY", "secret-test-key")
+    assert main(["propose", "--tool", "t", "--args", '{"a":1}']) == 0
+    entry = Ledger.open(root=root).read_entries()[0]
+    assert "seal" in entry
+    assert main(["verify"]) == 0
+    # tamper seal
+    path = Ledger.open(root=root).path
+    entry["seal"] = "00" * 32
+    path.write_text(json.dumps(entry, sort_keys=True) + "\n")
+    assert main(["verify"]) == 1
+
+
+def test_path_escape_rejected(root: Path) -> None:
+    with pytest.raises(LedgerError, match="path escapes"):
+        resolve_ledger_path(root=root, path="/etc/passwd")
+    # CLI path escape
+    assert main(["--ledger", "/tmp/evil.jsonl", "verify"]) == 2
+
+
+def test_args_hash_only(root: Path) -> None:
+    h = hash_args({"cmd": "echo"})
+    assert main(["propose", "--tool", "shell.exec", "--args-hash", h]) == 0
+    intent = Ledger.open(root=root).read_entries()[0]["intent"]
+    assert intent["args"] is None
+    assert intent["args_hash"] == h
+
+
+def test_build_intent_validation() -> None:
+    with pytest.raises(IntentError):
+        build_intent(tool="", args={})
+    with pytest.raises(IntentError):
+        build_intent(tool="t")
+    with pytest.raises(IntentError):
+        build_intent(tool="t", args={"a": 1}, args_hash="nope")
+
+
+def test_missing_ledger_setup_error(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.chdir(tmp_path)
+    assert main(["verify"]) == 2
+    assert main(["list"]) == 2
+
+
+def test_double_decision_setup_error(root: Path) -> None:
+    assert main(["propose", "--tool", "t", "--args", "{}"]) == 0
+    iid = Ledger.open(root=root).read_entries()[0]["intent_id"]
+    assert main(["approve", iid]) == 0
+    assert main(["deny", iid]) == 2
+
+
+def test_forged_consistent_chain_verifies_without_seal(root: Path) -> None:
+    """Without ACTGATE_SEAL_KEY, verify is integrity-only (not authenticity)."""
+    from actgate.core.ledger import compute_entry_hash
+
+    assert main(["propose", "--tool", "shell.exec", "--args", '{"cmd":"ls"}']) == 0
+    iid = Ledger.open(root=root).read_entries()[0]["intent_id"]
+    assert main(["approve", iid]) == 0
+    ledger = Ledger.open(root=root)
+    propose, approve = ledger.read_entries()
+    intent = dict(propose["intent"])
+    intent["tool"] = "forged.exec"
+    forged_propose = {
+        "seq": 1,
+        "action": "propose",
+        "intent_id": iid,
+        "intent": intent,
+        "prev_hash": GENESIS,
+        "created_at": propose.get("ts", propose.get("created_at")),
+    }
+    forged_propose["entry_hash"] = compute_entry_hash(forged_propose)
+    forged_approve = {
+        "seq": 2,
+        "action": "approve",
+        "intent_id": iid,
+        "intent": intent,
+        "decision": "approved",
+        "reason": approve.get("reason"),
+        "prev_hash": forged_propose["entry_hash"],
+        "created_at": approve.get("ts", approve.get("created_at")),
+    }
+    forged_approve["entry_hash"] = compute_entry_hash(forged_approve)
+    ledger.path.write_text(
+        json.dumps(forged_propose, sort_keys=True)
+        + "\n"
+        + json.dumps(forged_approve, sort_keys=True)
+        + "\n"
+    )
+    assert main(["verify"]) == 0
+    assert verify_ledger(ledger).ok
+    assert main(["verify", "--require-seal"]) == 1