Metadata-Version: 2.4
Name: stipul
Version: 0.2.1
Summary: Deterministic enforcement and cryptographic evidence for AI agent actions
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: asn1crypto>=1.5.1
Requires-Dist: cryptography>=41
Requires-Dist: mcp<2,>=1
Requires-Dist: PyYAML>=6
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Provides-Extra: dev
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: wheel>=0.45; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: bandit>=1.7; extra == "dev"

# Stipul

Your agents act. Can you prove what they did?

## What Stipul does

Stipul is a runtime authorization and evidence layer for AI agents. It intercepts tool calls, enforces policy, and produces a cryptographic proof chain around each decision. Writ enforces the Charter, records every decision in the Chronicle, and produces a cryptographic Seal. One command shows enforcement, evidence, verification, and tamper detection.

## See it work

Requires Python 3.10+. On systems with externally managed Python environments,
global pip install may be blocked. Use a virtual environment or pipx.

```bash
# Recommended — virtual environment
python3 -m venv .venv
.venv/bin/pip install stipul
.venv/bin/stipul demo proof

# Optional — isolated app install via pipx
pipx install stipul
stipul demo proof
```

```text
═══ Stipul Proof Demo ═══

Session: proof-demo

  seq 1  allow   filesystem.read      reason: allowed_tool
  seq 2  deny    web.search           reason: not_in_egress_allowlist
  seq 3  deny    shell.exec           reason: never_allow_tools
  seq 4  close   session_close

Trust: VERIFIED
  Chain: INTACT
  Seal:  VALID
  Decisions: 3
  Fingerprint: proof-demo | INTACT | VALID | 3 decisions | <hash>

═══ Tamper Challenge ═══

The seal records a cryptographic attestation over the session evidence.
Inspect it yourself, verify the session as-is, then change a recorded value and re-verify.

Step 1 — View the current seal:

  cat /tmp/stipul-proof-demo-<id>/session/seal.json | python3 -m json.tool

Step 2 — Verify the session as-is:

  stipul verify /tmp/stipul-proof-demo-<id>/session

Step 3 — Now tamper with the seal:

  sed -i 's/"terminal_sequence_id": <N>/"terminal_sequence_id": 999/' \
    /tmp/stipul-proof-demo-<id>/session/seal.json

Step 4 — Re-verify the session:

  stipul verify /tmp/stipul-proof-demo-<id>/session

Proof complete: enforcement decisions recorded, chained, and sealed.
```

Run the demo locally, follow the tamper challenge steps, and watch the trust
verdict flip from VERIFIED to REJECTED.
This demo runs locally with no external dependencies or framework integration.

## Architecture

**Writ** intercepts tool calls at the runtime boundary and applies policy before execution.

**Charter** defines what an agent is allowed to do, expressed as declarative rules.

**Chronicle** records every enforcement decision as a tamper-evident event chain.

**Seal** binds the recorded evidence to a cryptographic attestation that verification can check.

## When you need this

If a support agent can read local files and call web tools, you need a record showing which reads were allowed, which outbound requests were denied, and whether that evidence changed after the run. If a coding agent can touch the filesystem and invoke shell commands, you need policy enforcement and a sealed session trail before you let it operate in CI or against a shared repository. If an internal ops agent can inspect tickets, secrets, or deployment tooling, you need verification that the observed tool trace is the same one the runtime authorized.

## Claude Code Integration

Use Stipul to put Claude Code in read-only review mode — allow file reads, block writes and shell commands, verify the session afterward with a sealed receipt.

See the full walkthrough: [Claude Code Quickstart](docs/claude-code-quickstart.md)

## Links

PyPI: https://pypi.org/project/stipul/
GitHub: https://github.com/miadco/stipul
