obstat 0.1.0__py3-none-any.whl

obstat/__init__.py

@@ -0,0 +1,11 @@
+"""obstat — an auditable decision record for agent tool calls.
+
+*nihil obstat*: nothing stands in the way. The clearance is written down before
+the act, not reconstructed after it.
+"""
+
+from .guard import Denied, Subject, guard, set_subject_resolver
+from .policy import PolicyError
+
+__all__ = ["Denied", "PolicyError", "Subject", "guard", "set_subject_resolver"]
+__version__ = "0.1.0"

obstat/__main__.py

@@ -0,0 +1,87 @@
+"""`obstat` — the operator's side: what is waiting, and what happened.
+
+obstat pending
+obstat approve <id>
+obstat deny <id>
+obstat log [-n 20]
+obstat stop | resume
+"""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import sys
+import time
+
+from . import approval, paths, record
+
+
+def _pending(_: argparse.Namespace) -> int:
+    rows = approval.pending()
+    if not rows:
+        print("nothing waiting")
+        return 0
+    for row in rows:
+        left = int(row.expires - time.time())
+        print(f"{row.id}  {row.tool:24}  {row.subject:20}  {row.resource:30}  {left}s left")
+    return 0
+
+
+def _decide(args: argparse.Namespace) -> int:
+    who = args.by or getpass.getuser()
+    if approval.resolve(args.id, approved=args.approved, by=who):
+        print(f"{args.id} {'approved' if args.approved else 'denied'} by {who}")
+        return 0
+    # Already decided, already used, or never existed — all the same to the operator.
+    print(f"{args.id}: no pending approval by that id", file=sys.stderr)
+    return 1
+
+
+def _log(args: argparse.Namespace) -> int:
+    entries = record.read()
+    for entry in entries[-args.n :]:
+        print(json.dumps(entry))
+    return 0
+
+
+def _stop(_: argparse.Namespace) -> int:
+    path = paths.halt()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(f"stopped by {getpass.getuser()} at {time.time()}\n", encoding="utf-8")
+    print(f"stopped. Every guarded call is denied until `obstat resume`. ({path})")
+    return 0
+
+
+def _resume(_: argparse.Namespace) -> int:
+    paths.halt().unlink(missing_ok=True)
+    print("resumed")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="obstat", description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("pending", help="approvals waiting on a human").set_defaults(run=_pending)
+
+    for verb, approved in (("approve", True), ("deny", False)):
+        cmd = sub.add_parser(verb, help=f"{verb} a pending approval")
+        cmd.add_argument("id")
+        cmd.add_argument("--by", help="who decided (default: the shell user)")
+        cmd.set_defaults(run=_decide, approved=approved)
+
+    log = sub.add_parser("log", help="the decision record, oldest first")
+    log.add_argument("-n", type=int, default=20, help="how many entries (default 20)")
+    log.set_defaults(run=_log)
+
+    sub.add_parser("stop", help="deny every guarded call").set_defaults(run=_stop)
+    sub.add_parser("resume", help="undo stop").set_defaults(run=_resume)
+
+    args = parser.parse_args(argv)
+    return int(args.run(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

obstat/approval.py

@@ -0,0 +1,139 @@
+"""Two-phase approval (§4).
+
+Phase 1: the call arrives, policy says `approve`, and the tool returns an
+approval id instead of doing anything. Phase 2: a human decides, the agent calls
+again with the id, and the call proceeds.
+
+The agent is never blocked waiting on a human, because most agents are not
+sitting at a terminal. That is the only reason this is a state machine in SQLite
+rather than an `input()` call.
+
+An approval is bound to the exact call it was granted for — tool, subject,
+resource and argument digest — and is single-use. Approving "send the email"
+must not authorise sending a different one.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import time
+import uuid
+from dataclasses import dataclass
+
+from . import paths
+
+TTL_SECONDS = 900  # 15 minutes: long enough to reach a human, short enough to expire
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS approvals (
+    id           TEXT PRIMARY KEY,
+    created      REAL NOT NULL,
+    expires      REAL NOT NULL,
+    tool         TEXT NOT NULL,
+    subject      TEXT NOT NULL,
+    resource     TEXT NOT NULL,
+    args_digest  TEXT NOT NULL,
+    record_id    TEXT NOT NULL,
+    state        TEXT NOT NULL CHECK (state IN ('pending','approved','denied','consumed')),
+    decided_by   TEXT,
+    decided_at   REAL
+);
+"""
+
+
+@dataclass(frozen=True)
+class Pending:
+    id: str
+    tool: str
+    subject: str
+    resource: str
+    created: float
+    expires: float
+
+
+def _connect() -> sqlite3.Connection:
+    path = paths.db()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # isolation_level=None: explicit BEGIN IMMEDIATE where it matters, autocommit
+    # elsewhere. WAL so a human running the CLI cannot block a serving process.
+    conn = sqlite3.connect(path, isolation_level=None, timeout=5.0)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute(_SCHEMA)
+    return conn
+
+
+def request(
+    *, tool: str, subject: str, resource: str, args_digest: str, record_id: str
+) -> tuple[str, int]:
+    """Open a pending approval. Returns its id and how long it is valid for."""
+    approval_id = uuid.uuid4().hex[:12]  # short enough to read out loud over a call
+    now = time.time()
+    with _connect() as conn:
+        conn.execute(
+            "INSERT INTO approvals (id, created, expires, tool, subject, resource,"
+            " args_digest, record_id, state) VALUES (?,?,?,?,?,?,?,?,'pending')",
+            (approval_id, now, now + TTL_SECONDS, tool, subject, resource, args_digest, record_id),
+        )
+    return approval_id, TTL_SECONDS
+
+
+def resolve(approval_id: str, *, approved: bool, by: str) -> bool:
+    """A human decides. Returns False if there was no pending approval by that id."""
+    state = "approved" if approved else "denied"
+    with _connect() as conn:
+        cursor = conn.execute(
+            "UPDATE approvals SET state=?, decided_by=?, decided_at=?"
+            " WHERE id=? AND state='pending'",
+            (state, by, time.time(), approval_id),
+        )
+        return cursor.rowcount == 1
+
+
+def consume(
+    approval_id: str, *, tool: str, subject: str, resource: str, args_digest: str
+) -> tuple[bool, str]:
+    """Spend an approval on exactly the call it was granted for.
+
+    Returns (ok, reason). The check and the state change happen inside one
+    IMMEDIATE transaction, so two concurrent retries cannot both win.
+    """
+    with _connect() as conn:
+        conn.execute("BEGIN IMMEDIATE")
+        try:
+            row = conn.execute("SELECT * FROM approvals WHERE id=?", (approval_id,)).fetchone()
+            if row is None:
+                return False, "unknown approval"
+            if row["state"] == "consumed":
+                return False, "approval already used"
+            if row["state"] != "approved":
+                return False, f"approval is {row['state']}"
+            if row["expires"] < time.time():
+                return False, "approval expired"
+            # The binding check. Each of these being wrong means the agent is
+            # retrying with an approval granted for a different call.
+            for field, actual in (
+                ("tool", tool),
+                ("subject", subject),
+                ("resource", resource),
+                ("args_digest", args_digest),
+            ):
+                if row[field] != actual:
+                    return False, f"approval was granted for a different {field}"
+            conn.execute("UPDATE approvals SET state='consumed' WHERE id=?", (approval_id,))
+            conn.execute("COMMIT")
+            return True, "approved"
+        except BaseException:
+            conn.execute("ROLLBACK")
+            raise
+
+
+def pending() -> list[Pending]:
+    """Everything still waiting on a human, oldest first. Expired entries are hidden."""
+    with _connect() as conn:
+        rows = conn.execute(
+            "SELECT id, tool, subject, resource, created, expires FROM approvals"
+            " WHERE state='pending' AND expires > ? ORDER BY created",
+            (time.time(),),
+        ).fetchall()
+    return [Pending(**dict(row)) for row in rows]

obstat/guard.py

@@ -0,0 +1,329 @@
+"""`@guard` — the decorator, and the order it does things in (§3).
+
+    1  reject a caller-supplied subject
+    2  stop file
+    3  resolve the resource from the arguments
+    4  policy
+    5  approval, if policy asked for one
+    6  write the decision record — durable
+    7  run the body
+    8  write the outcome — best effort
+
+Step 6 is before step 7 and that is not a stylistic choice. Everything a reader
+needs to trust the record depends on it.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from . import approval, paths, policy, record
+
+ANONYMOUS = policy.ANONYMOUS
+APPROVAL_ARG = "obstat_approval_id"
+
+
+class Denied(Exception):
+    """Refused. Carries the record id and nothing else.
+
+    A denial that explains itself teaches a caller which rule to work around, so
+    the detail lives in the record, where the operator can read it and the agent
+    cannot.
+    """
+
+    def __init__(self, record_id: str) -> None:
+        super().__init__(f"Not permitted. Do not retry. Reference: {record_id}")
+        self.record_id = record_id
+
+
+class _Pending(Exception):
+    """Not an error: an approval was opened and the agent should come back.
+
+    Raised only because it unwinds the same path a denial does; the wrapper turns
+    it into a return value, because a call that needs a human has not failed.
+    """
+
+    def __init__(self, approval_id: str, ttl: int, record_id: str) -> None:
+        super().__init__(approval_id)
+        self.approval_id = approval_id
+        self.ttl = ttl
+        self.record_id = record_id
+
+    def payload(self) -> dict[str, Any]:
+        return {
+            "obstat": "approval_required",
+            "approval_id": self.approval_id,
+            "expires_in_seconds": self.ttl,
+            "record": self.record_id,
+            "retry": (
+                "A human must approve this call. Once approved, call the same tool "
+                f"again with identical arguments plus {APPROVAL_ARG}='{self.approval_id}'."
+            ),
+        }
+
+
+@dataclass(frozen=True)
+class Subject:
+    """Who is calling, as far as the host application can tell.
+
+    `verified` is the honest flag: False means the identity came from somewhere a
+    caller could have influenced — a header, an argument, a config file.
+
+    ponytail: policy matches on `kind:id` and ignores `verified`, which is
+    recorded but not enforced. Gate on it in your resolver (return None rather
+    than an unverified Subject) until there is a reason for a rule to say so.
+    """
+
+    id: str
+    kind: Literal["human", "agent", "service"] = "agent"
+    via: tuple[str, ...] = ()  # delegation chain, most recent first
+    verified: bool = False
+
+    def __str__(self) -> str:
+        return f"{self.kind}:{self.id}"
+
+
+def _no_subject() -> Subject | None:
+    return None
+
+
+_resolver: Callable[[], Subject | None] = _no_subject
+
+
+def set_subject_resolver(resolver: Callable[[], Subject | None]) -> None:
+    """Tell obstat how to find out who is calling.
+
+    Called with no arguments on every guarded call; return None when there is no
+    identity, which is the normal case for a stdio MCP server on a laptop. An
+    anonymous call is a legitimate call — it is recorded as `anonymous`, and the
+    policy decides what that may do.
+    """
+    global _resolver
+    _resolver = resolver
+
+
+@dataclass(frozen=True)
+class _Checked:
+    """What steps 1-5 established, handed to step 6."""
+
+    subject: Subject | None
+    subject_name: str
+    resource: str
+    args_digest: str
+    verdict: policy.Decision
+    approval_id: str | None
+
+
+def _public_signature(fn: Callable[..., Any]) -> inspect.Signature:
+    """The signature callers see: `subject` removed, `obstat_approval_id` added.
+
+    `subject` is injected by obstat, so leaving it in the advertised schema would
+    invite a client to supply its own. The approval id is the opposite — the
+    retry protocol needs the caller to send it, so it has to be advertised.
+    """
+    original = inspect.signature(fn)
+    kept = [p for name, p in original.parameters.items() if name != "subject"]
+    var_keyword = [p for p in kept if p.kind is inspect.Parameter.VAR_KEYWORD]
+    positional = [p for p in kept if p.kind is not inspect.Parameter.VAR_KEYWORD]
+    approval_param = inspect.Parameter(
+        APPROVAL_ARG,
+        inspect.Parameter.KEYWORD_ONLY,
+        default=None,
+        annotation="str | None",
+    )
+    return original.replace(parameters=[*positional, approval_param, *var_keyword])
+
+
+def _resource_for(
+    spec: str | Callable[[dict[str, Any]], str] | None, tool: str, args: dict[str, Any]
+) -> str:
+    if spec is None:
+        return f"tool:{tool}"
+    if callable(spec):
+        return spec(args)
+    return spec.format(**args)
+
+
+def guard(
+    *,
+    resource: str | Callable[[dict[str, Any]], str] | None = None,
+    tool: str | None = None,
+):
+    """Wrap a tool so that no call happens without a written decision.
+
+        @guard(resource="jira_issue:{issue_key}")
+        def transition_issue(issue_key: str, transition: str) -> str:
+            ...
+
+    `resource` is a format template over the call arguments, or a callable that
+    takes them. Omit it and the resource is `tool:<name>`, which is enough when
+    the tool is the only thing policy needs to distinguish.
+    """
+
+    def decorate(fn: Callable[..., Any]) -> Callable[..., Any]:
+        name = tool or fn.__name__
+        wants_subject = "subject" in inspect.signature(fn).parameters
+        public = _public_signature(fn)
+        # Arguments are bound against the public signature minus the approval id,
+        # so the digest covers what the tool will actually receive and nothing else.
+        bind_against = public.replace(
+            parameters=[p for p in public.parameters.values() if p.name != APPROVAL_ARG]
+        )
+
+        def refuse(
+            reason: str,
+            *,
+            subject: str = ANONYMOUS,
+            resource_id: str | None = None,
+            args_digest: str | None = None,
+            rule: int | None = None,
+            approval_id: str | None = None,
+        ) -> Denied:
+            return Denied(
+                record.decision(
+                    tool=name,
+                    subject=subject,
+                    resource=resource_id or f"tool:{name}",
+                    effect="deny",
+                    reason=reason,
+                    rule=rule,
+                    args_digest=args_digest or record.digest({}),
+                    approval_id=approval_id,
+                )
+            )
+
+        def check(args: tuple, kwargs: dict) -> _Checked:
+            """Steps 1-5. Raises Denied, raises _Pending, or returns."""
+            approval_id = kwargs.pop(APPROVAL_ARG, None)
+
+            # 1. `subject` is not advertised, so its presence is a caller trying to
+            #    say who it is. Denied before anything reads it — including the
+            #    record, which would otherwise quote an attacker's string.
+            if "subject" in kwargs:
+                raise refuse("caller supplied a subject")
+
+            try:
+                bound = bind_against.bind_partial(*args, **kwargs)
+            except TypeError as exc:
+                raise refuse(f"arguments do not fit the tool: {exc}") from exc
+            bound.apply_defaults()
+            call_args = dict(bound.arguments)
+            args_digest = record.digest(call_args)
+
+            who = _resolver()
+            subject = str(who) if who is not None else ANONYMOUS
+
+            # 2. The stop file, before policy: stopping must not depend on the
+            #    policy file still being parseable.
+            if paths.halt().exists():
+                raise refuse("halted", subject=subject, args_digest=args_digest)
+
+            # 3. Resource.
+            try:
+                target = _resource_for(resource, name, call_args)
+            except (KeyError, IndexError, AttributeError, TypeError) as exc:
+                raise refuse(
+                    f"resource template did not resolve: {exc!r}",
+                    subject=subject,
+                    resource_id="unresolved",
+                    args_digest=args_digest,
+                ) from exc
+
+            # 4. Policy. Evaluated once; step 6 records this verdict, not a re-read.
+            verdict = policy.decide(tool=name, subject=subject, resource=target)
+            refusal = functools.partial(
+                refuse, subject=subject, resource_id=target, args_digest=args_digest
+            )
+            if verdict.effect == "deny":
+                raise refusal(verdict.reason, rule=verdict.rule)
+
+            # 5. Approval.
+            if verdict.effect == "approve":
+                if approval_id is None:
+                    record_id = record.decision(
+                        tool=name,
+                        subject=subject,
+                        resource=target,
+                        effect="approval_required",
+                        reason=verdict.reason,
+                        rule=verdict.rule,
+                        args_digest=args_digest,
+                    )
+                    new_id, ttl = approval.request(
+                        tool=name,
+                        subject=subject,
+                        resource=target,
+                        args_digest=args_digest,
+                        record_id=record_id,
+                    )
+                    raise _Pending(new_id, ttl, record_id)
+                ok, why = approval.consume(
+                    approval_id,
+                    tool=name,
+                    subject=subject,
+                    resource=target,
+                    args_digest=args_digest,
+                )
+                if not ok:
+                    raise refusal(why, rule=verdict.rule, approval_id=approval_id)
+
+            return _Checked(who, subject, target, args_digest, verdict, approval_id)
+
+        def authorise(args: tuple, kwargs: dict) -> tuple[str, dict]:
+            """Steps 1-6. Returns the record id and the kwargs the body will get."""
+            checked = check(args, kwargs)
+            record_id = record.decision(
+                tool=name,
+                subject=checked.subject_name,
+                resource=checked.resource,
+                effect="allow",
+                reason=checked.verdict.reason,
+                rule=checked.verdict.rule,
+                args_digest=checked.args_digest,
+                approval_id=checked.approval_id,
+                extra={"subject_verified": bool(checked.subject and checked.subject.verified)},
+            )
+            if wants_subject:
+                kwargs = {**kwargs, "subject": checked.subject}
+            return record_id, kwargs
+
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def wrapper(*args: Any, **kwargs: Any) -> Any:
+                try:
+                    record_id, kwargs = authorise(args, dict(kwargs))
+                except _Pending as pending:
+                    return pending.payload()
+                try:
+                    result = await fn(*args, **kwargs)
+                except Exception as exc:
+                    record.outcome(record_id, ok=False, error=type(exc).__name__)
+                    raise
+                record.outcome(record_id, ok=True)
+                return result
+
+        else:
+
+            @functools.wraps(fn)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                try:
+                    record_id, kwargs = authorise(args, dict(kwargs))
+                except _Pending as pending:
+                    return pending.payload()
+                try:
+                    result = fn(*args, **kwargs)
+                except Exception as exc:
+                    record.outcome(record_id, ok=False, error=type(exc).__name__)
+                    raise
+                record.outcome(record_id, ok=True)
+                return result
+
+        wrapper.__signature__ = public  # type: ignore[attr-defined]
+        return wrapper
+
+    return decorate

obstat/paths.py

@@ -0,0 +1,34 @@
+"""Where obstat keeps things.
+
+Read at call time, never at import. A governance library that raises
+`ConfigError` on import is one you cannot try, and a library you cannot try is
+one nobody adopts — which is worse for security than a permissive default.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+DEFAULT_DIR = ".obstat"
+
+
+def _env(name: str, default: str) -> Path:
+    return Path(os.environ.get(name) or default).expanduser()
+
+
+def policy() -> Path:
+    return _env("OBSTAT_POLICY", "obstat.toml")
+
+
+def log() -> Path:
+    return _env("OBSTAT_LOG", f"{DEFAULT_DIR}/decisions.jsonl")
+
+
+def db() -> Path:
+    return _env("OBSTAT_DB", f"{DEFAULT_DIR}/approvals.db")
+
+
+def halt() -> Path:
+    """Presence of this file stops every guarded call. Deleting it resumes."""
+    return _env("OBSTAT_HALT", f"{DEFAULT_DIR}/halt")

obstat/policy.py

@@ -0,0 +1,109 @@
+"""Rules, and the decision they produce (§2).
+
+A rule matches on three things — who, which tool, which object — and says one of
+`allow`, `deny`, `approve`. First match wins. Nothing matching is a deny: an
+absent rule is not permission.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from fnmatch import fnmatchcase
+from pathlib import Path
+from typing import Literal
+
+from . import paths
+
+Effect = Literal["allow", "deny", "approve"]
+EFFECTS: tuple[Effect, ...] = ("allow", "deny", "approve")
+
+ANONYMOUS = "anonymous"
+
+
+class PolicyError(RuntimeError):
+    """The policy file is missing or malformed. Raised on the first guarded call."""
+
+
+@dataclass(frozen=True)
+class Rule:
+    effect: Effect
+    tool: str = "*"
+    subject: str = "*"
+    resource: str = "*"
+
+    def matches(self, *, tool: str, subject: str, resource: str) -> bool:
+        return (
+            fnmatchcase(tool, self.tool)
+            and fnmatchcase(subject, self.subject)
+            and fnmatchcase(resource, self.resource)
+        )
+
+
+@dataclass(frozen=True)
+class Decision:
+    effect: Effect
+    reason: str
+    rule: int | None  # index into the file, so a record points at the line that decided
+
+
+_DENY_UNMATCHED = Decision("deny", "no rule matched", None)
+
+# (path, mtime, size) -> rules. Editing the policy takes effect on the next call
+# rather than the next restart; a stat() per call is cheaper than the confusion.
+_cache: tuple[tuple[str, float, int], list[Rule]] | None = None
+
+
+def _parse(raw: dict) -> list[Rule]:
+    rules: list[Rule] = []
+    for index, entry in enumerate(raw.get("rule", [])):
+        if not isinstance(entry, dict):
+            raise PolicyError(f"rule {index}: expected a table")
+        effect = entry.get("effect")
+        if effect not in EFFECTS:
+            raise PolicyError(f"rule {index}: effect must be one of {', '.join(EFFECTS)}")
+        unknown = set(entry) - {"effect", "tool", "subject", "resource"}
+        if unknown:
+            # A typo'd key would otherwise silently widen the rule to match everything.
+            raise PolicyError(f"rule {index}: unknown key(s) {', '.join(sorted(unknown))}")
+        rules.append(
+            Rule(
+                effect=effect,
+                tool=str(entry.get("tool", "*")),
+                subject=str(entry.get("subject", "*")),
+                resource=str(entry.get("resource", "*")),
+            )
+        )
+    return rules
+
+
+def load(path: Path | None = None) -> list[Rule]:
+    global _cache
+    path = path or paths.policy()
+    try:
+        stat = path.stat()
+    except FileNotFoundError as exc:
+        raise PolicyError(
+            f"no policy at {path}. Write one (see README) or set OBSTAT_POLICY. "
+            "obstat has no implicit allow."
+        ) from exc
+
+    key = (str(path), stat.st_mtime, stat.st_size)
+    if _cache is not None and _cache[0] == key:
+        return _cache[1]
+
+    try:
+        raw = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise PolicyError(f"{path}: {exc}") from exc
+
+    rules = _parse(raw)
+    _cache = (key, rules)
+    return rules
+
+
+def decide(*, tool: str, subject: str, resource: str, path: Path | None = None) -> Decision:
+    for index, rule in enumerate(load(path)):
+        if rule.matches(tool=tool, subject=subject, resource=resource):
+            return Decision(rule.effect, f"rule {index}", index)
+    return _DENY_UNMATCHED

obstat/record.py

@@ -0,0 +1,122 @@
+"""The decision record (§5), and the one ordering that is a security property.
+
+`decision()` returns only after the record is on disk — written, flushed, and
+fsynced. Everything else in this library is a convenience; this is the part an
+examiner relies on. A log written after the call is a story about what happened.
+A record written before it is evidence of what was authorised.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import os
+import time
+import uuid
+from pathlib import Path
+from typing import Any
+
+from . import paths
+
+SCHEMA = 1
+
+
+def digest(args: dict[str, Any]) -> str:
+    """A stable fingerprint of the call arguments.
+
+    The values themselves are deliberately not recorded: tool arguments carry
+    credentials, personal data and free text, and a governance log that leaks
+    them is a liability rather than a control. The digest is enough to prove
+    that the call executed is the call that was approved.
+
+    ponytail: no per-key allowlist yet. Add `record_args=("issue_key",)` to
+    @guard when someone needs the values in the record itself.
+    """
+    canonical = json.dumps(args, sort_keys=True, default=repr, separators=(",", ":"))
+    return "sha256:" + hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def _append(entry: dict[str, Any], *, durable: bool) -> None:
+    path = paths.log()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    line = json.dumps(entry, separators=(",", ":"), default=str) + "\n"
+    # Append mode, one write, one line: concurrent writers interleave records but
+    # never split one. O_APPEND makes the offset kernel-side, so no lock is needed.
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(line)
+        if durable:
+            handle.flush()
+            os.fsync(handle.fileno())
+
+
+def decision(
+    *,
+    tool: str,
+    subject: str,
+    resource: str,
+    effect: str,
+    reason: str,
+    rule: int | None,
+    args_digest: str,
+    approval_id: str | None = None,
+    extra: dict[str, Any] | None = None,
+) -> str:
+    """Write the decision. Returns the record id, which is also the deny reference.
+
+    Durable before the caller continues — that is the whole point, and
+    `tests/test_guard.py::test_record_is_durable_before_the_body_runs` fails if
+    this is ever relaxed for speed.
+    """
+    record_id = uuid.uuid4().hex
+    _append(
+        {
+            "schema": SCHEMA,
+            "id": record_id,
+            "ts": time.time(),
+            "phase": "decision",
+            "tool": tool,
+            "subject": subject,
+            "resource": resource,
+            "effect": effect,
+            "reason": reason,
+            "rule": rule,
+            "args": args_digest,
+            "approval_id": approval_id,
+            **(extra or {}),
+        },
+        durable=True,
+    )
+    return record_id
+
+
+def outcome(record_id: str, *, ok: bool, error: str | None = None) -> None:
+    """Best effort, and deliberately not durable.
+
+    If the process dies mid-call the decision record still stands alone, which
+    reads as "authorised, outcome unknown" — the honest state. Blocking the
+    caller on a second fsync to record something that is only informative would
+    be paying the cost twice for half the value.
+    """
+    # A full disk must not turn a completed call into a failed one.
+    with contextlib.suppress(OSError):
+        _append(
+            {
+                "schema": SCHEMA,
+                "id": record_id,
+                "ts": time.time(),
+                "phase": "outcome",
+                "ok": ok,
+                "error": error,
+            },
+            durable=False,
+        )
+
+
+def read(path: Path | None = None) -> list[dict[str, Any]]:
+    """Every record, oldest first. For tests and for `obstat log`."""
+    path = path or paths.log()
+    if not path.exists():
+        return []
+    with path.open(encoding="utf-8") as handle:
+        return [json.loads(line) for line in handle if line.strip()]

obstat-0.1.0.dist-info/METADATA

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: obstat
+Version: 0.1.0
+Summary: An auditable decision record for agent tool calls. The clearance is written down before the call runs.
+Project-URL: Homepage, https://github.com/marcinmarzeta/obstat
+Project-URL: Issues, https://github.com/marcinmarzeta/obstat/issues
+Author: Marcin Marzęta
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,approval,audit,authorization,llm,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Provides-Extra: mcp
+Requires-Dist: mcp>=2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# obstat
+
+**An auditable decision record for agent tool calls.** The clearance is written
+down before the call runs — not reconstructed from logs afterwards.
+
+*Nihil obstat*: nothing stands in the way. It was the formal clearance a censor
+granted **in writing, before publication**. That is the whole idea here. An agent
+asks to do something, a rule decides, and the decision goes to disk *before* the
+tool body executes. If the process dies mid-call, the record still says what was
+authorised and why.
+
+```bash
+pip install obstat
+```
+
+No dependencies. Not AWS, not an identity provider, not a policy service — the
+decorator, `tomllib`, `sqlite3` and a file.
+
+## 60 seconds
+
+`obstat.toml`:
+
+```toml
+[[rule]]
+tool = "read_*"
+effect = "allow"
+
+[[rule]]
+tool = "delete_*"
+effect = "approve"
+```
+
+Your tool:
+
+```python
+from obstat import guard
+
+
+@guard(resource="doc:{doc_id}")
+def delete_document(doc_id: str) -> str: ...  # obstat has already decided this may happen
+```
+
+First call returns instead of running:
+
+```python
+>>> delete_document("q3-report")
+{'obstat': 'approval_required',
+ 'approval_id': '4f1c2a9b8e07',
+ 'expires_in_seconds': 900,
+ 'retry': "A human must approve this call. Once approved, call the same tool
+           again with identical arguments plus obstat_approval_id='4f1c2a9b8e07'."}
+```
+
+A human decides:
+
+```console
+$ obstat pending
+4f1c2a9b8e07  delete_document  anonymous  doc:q3-report  871s left
+$ obstat approve 4f1c2a9b8e07
+4f1c2a9b8e07 approved by ana
+```
+
+The agent retries with the id, the call runs, and `.obstat/decisions.jsonl` holds
+the whole story.
+
+## What it is not
+
+There are several good libraries that gate MCP tool calls. This one is built
+around a narrower claim: **the record is the product.** Three things follow from
+that, and they are the reason to pick this over a permission wrapper.
+
+**The decision is durable before the body runs.** Not flushed after, not written
+in a `finally`, not batched. `record.decision()` returns only after `fsync`. A log
+written after the fact is a story about what happened; a record written before it
+is evidence of what was authorised. There is a test that runs inside a tool body,
+reads the log off disk, and fails if its own decision record is not already there.
+
+**Authorisation is per resource, not per tool.** A tier — READ, WRITE,
+DESTRUCTIVE — cannot say "may edit their own ticket, not yours". obstat resolves
+the resource from the call arguments and matches rules against it:
+
+```python
+@guard(resource="jira_issue:{issue_key}")
+```
+
+```toml
+[[rule]]
+subject = "human:ana"
+resource = "jira_issue:ACME-*"
+effect = "allow"
+```
+
+**An approval is bound to one call.** It carries the tool, the subject, the
+resource and a digest of the arguments, and it is single-use. Approving "delete
+q3-report" cannot be spent on deleting something else, and cannot be spent twice.
+This is enforced in one `BEGIN IMMEDIATE` transaction, so two concurrent retries
+cannot both win.
+
+## Identity is optional
+
+Most MCP servers today have no token at all: stdio, one local user, or a gateway
+that already terminated auth. Demanding an identity provider before you can try a
+governance library is why governance libraries go untried. An anonymous call is a
+legitimate call here — it is recorded as `anonymous`, and the policy decides what
+`anonymous` may do.
+
+When you *do* have identity, hand it over:
+
+```python
+from obstat import Subject, set_subject_resolver
+
+set_subject_resolver(lambda: Subject(id=current_user(), kind="human", verified=True))
+```
+
+`verified=False` is the honest flag for identity that came from somewhere a caller
+could influence — a header, an argument. It is recorded, so a reader can tell the
+difference between "Ana did this" and "something claimed to be Ana did this".
+
+## Policy
+
+First matching rule wins. Nothing matching is a deny — an absent rule is not
+permission, and a missing policy file is an error rather than an implicit allow.
+
+| key | matches | default |
+|---|---|---|
+| `tool` | the function name, or `tool=` on the decorator | `*` |
+| `subject` | `human:ana`, `agent:planner`, `service:etl`, `anonymous` | `*` |
+| `resource` | whatever the resource template produced | `*` |
+| `effect` | `allow`, `deny`, `approve` | required |
+
+Patterns are globs. The file is re-read when it changes, so editing policy does
+not need a restart.
+
+## The order
+
+```
+1  reject a caller-supplied subject
+2  stop file
+3  resolve the resource from the arguments
+4  policy
+5  approval, if policy asked for one
+6  write the decision record — durable      <-- before, not after
+7  run the body
+8  write the outcome — best effort
+```
+
+Step 1 exists because `subject` is stripped from the tool's advertised signature.
+A client that sends one anyway is trying to name itself, and that is a denial
+before anything reads the value.
+
+Step 8 is deliberately not durable. If the process dies between 7 and 8 the record
+reads "authorised, outcome unknown", which is the honest state; paying for a second
+`fsync` to say something merely informative is the wrong trade.
+
+## Operator commands
+
+```console
+obstat pending              # approvals waiting on a human
+obstat approve <id> [--by]  # decide
+obstat deny <id> [--by]
+obstat log -n 50            # the decision record
+obstat stop                 # deny every guarded call
+obstat resume
+```
+
+`obstat stop` is checked before policy, so stopping never depends on the policy
+file still being parseable.
+
+## What is not here yet
+
+Arguments are fingerprinted (`sha256:…`), never stored — tool arguments carry
+credentials and personal data, and a governance log that leaks them is a liability
+rather than a control. A per-key allowlist for recording chosen values is the
+obvious next step.
+
+Also absent, deliberately: retention and rotation of the log, Slack and webhook
+approval channels, a policy for where a result may be *sent*, and anything that
+talks to a cloud. Those belong at the edges, and the edges should be adapters
+rather than dependencies.
+
+## Configuration
+
+| variable | default |
+|---|---|
+| `OBSTAT_POLICY` | `obstat.toml` |
+| `OBSTAT_LOG` | `.obstat/decisions.jsonl` |
+| `OBSTAT_DB` | `.obstat/approvals.db` |
+| `OBSTAT_HALT` | `.obstat/halt` |
+
+Read at call time, never at import. A library that raises on import is a library
+you cannot try.
+
+## License
+
+Apache-2.0.

obstat-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+obstat/__init__.py,sha256=_aUFo10VnPb0dMqHr5I2YiPs6yMHT0AUeMdBCF2Z19M,387
+obstat/__main__.py,sha256=Q_1QxvXrnAy6bf3oNZwxVXLyNssI5ZW1X9ihokvQV3M,2694
+obstat/approval.py,sha256=0NIsog2d9g9HY8PudoBc9WL8DYLvjAAZc56_E2MiAeU,5092
+obstat/guard.py,sha256=blRKl0z2mgFAvWs_xoETjqyH0uq484lnpqHdNF4w3IE,12120
+obstat/paths.py,sha256=gfQKEgqNOf1aEv_JNzUlHTlM58TBvLV2v8yTvMV_Gz0,856
+obstat/policy.py,sha256=ks2evlfu4gRlxktpFiRYsAaOQ8WZ10XmBaNN8l6BENw,3465
+obstat/record.py,sha256=GJpOBHgwm0Uy9BcTw5Rvdo8ofMhLM1rXejhu4SgbMNI,3997
+obstat-0.1.0.dist-info/METADATA,sha256=PW3Z11Z9O_UR2NtwzV2ZDlRoSCWENtzWyoIgrPGFJEo,7151
+obstat-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+obstat-0.1.0.dist-info/entry_points.txt,sha256=kZZuze70AJ5aQHjtS1k5oeoAyC9jLlOUSHCjz6QSTEk,48
+obstat-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+obstat-0.1.0.dist-info/RECORD,,

obstat-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

obstat-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+obstat = obstat.__main__:main

obstat-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.