pic-standard 0.8.0

PIC Standard: Provenance & Intent Contracts for agentic side-effect governance

PIC Standard: Provenance & Intent Contracts

Local-first action gating for AI agents. Verify intent, provenance, and evidence before any high-impact tool call executes.

PIC is a lightweight, local-first protocol that forces AI agents to prove every important action before it happens. Agents must declare intent, impact, provenance, and evidence; PIC verifies everything and fails closed if anything is wrong.

No more hallucinations turning into wire transfers. No more prompt injections triggering data exports.

Example — when PIC blocks: A Slack message asks an LLM agent to send a $500 payment. PIC requires the agent to prove: where did this instruction come from? Is the source trusted? Is there evidence the invoice is real? The Slack message carries no trusted provenance, the claim has no backing evidence — PIC returns block. The payment tool never executes.

---

Table of Contents

• Why PIC?
• Quickstart
• The PIC Contract
• How It Works
• Evidence Verification
• Keyring (Trusted Signers)
• Integrations
• RFC & Prior Art
• Roadmap
• Contributing

---

Why PIC?

Guardrails constrain what the model says. PIC constrains what the agent is allowed to do based on verifiable provenance + evidence.

PIC is built for agent frameworks, internal tool gateways, and production systems where high-impact actions must be justified before execution.

• Stops prompt injections & blind tool calls at the action boundary
• Works 100% locally: zero cloud, zero data leaves your machine
• Plugs into your stack in minutes: LangGraph, MCP, OpenClaw, Cordum
• Open-source (Apache 2.0): audit it, fork it, own it

---

Quickstart

Try the verifier locally against a sample high-impact proposal in under a minute.

pip install pic-standard

# Verify an example proposal
pic-cli verify examples/financial_irreversible.json

# Evidence-aware verification (hash)
pic-cli verify examples/financial_hash_ok.json --verify-evidence

# Evidence-aware verification (signature — requires example keyring)
# macOS / Linux
PIC_KEYS_PATH=pic_keys.example.json pic-cli verify examples/financial_sig_ok.json --verify-evidence
# PowerShell
# $env:PIC_KEYS_PATH="pic_keys.example.json"
# pic-cli verify examples/financial_sig_ok.json --verify-evidence

Optional extras:

pip install "pic-standard[langgraph]"  # LangGraph PICToolNode
pip install "pic-standard[mcp]"        # MCP tool guarding
pip install "pic-standard[crypto]"     # Ed25519 signature evidence

From source (contributors):

git clone https://github.com/madeinplutofabio/pic-standard.git
cd pic-standard && pip install -e ".[langgraph,mcp,crypto]"
pytest -q

---

The PIC Contract

PIC is enforced at the moment before tool execution. The agent must emit a structured Action Proposal that can be validated, verified, and bound to the intended tool.

Field	Purpose
intent	What the agent is trying to do
impact	Risk class: money, privacy, irreversible, compute, ...
provenance	Which inputs influenced the decision (with trust levels)
claims + evidence	What the agent asserts and the evidence backing it
action	The actual tool call (tool binding)

Rule: For high-impact proposals, at least one claim must reference evidence from trusted provenance. Fail-closed.

---

How It Works

graph TD
    A[Untrusted Input] --> B{AI Agent / Planner}
    C[Trusted Data/DB] --> B
    B --> D[Action Proposal JSON]
    D --> E[PIC Verifier]
    E --> F{Valid Contract?}
    F -- Yes --> G[Tool Executor]
    F -- No --> H[Blocked / Alert Log]

---

Evidence Verification

PIC supports deterministic evidence verification that upgrades provenance trust in-memory.

Type	Description
hash	SHA-256 verification of file artifacts (file://...)
sig	Ed25519 signature verification via trusted keyring

Ed25519 signature verification requires pip install "pic-standard[crypto]".

# Verify hash evidence
pic-cli verify examples/financial_hash_ok.json --verify-evidence

# Verify signature evidence (requires keyring)
# macOS / Linux
PIC_KEYS_PATH=pic_keys.example.json pic-cli verify examples/financial_sig_ok.json --verify-evidence
# PowerShell
# $env:PIC_KEYS_PATH="pic_keys.example.json"
# pic-cli verify examples/financial_sig_ok.json --verify-evidence

Full guide: docs/evidence.md

Canonicalization (v0.8.0+): PIC Canonical JSON v1 (PIC-CJSON/1.0) defines the byte-exact serialization rules used when PIC hashes or signs JSON values. The normative spec is docs/canonicalization.md; a pure-stdlib reference implementation lives at pic_standard.canonical (canonicalize(), sha256_hex(), intent_digest_hex()). In v0.8.0 this is an additive capability — existing signature verification paths continue to work as in v0.7.x; wiring canonicalization into attestation-object-backed signatures is scheduled for a later release. Conformance vectors live under conformance/canonicalization/ and execute on every PR via the PIC Conformance CI job.

---

Keyring (Trusted Signers)

Signature evidence requires a keyring of trusted public keys with expiry and revocation support.

pic-cli keys                        # Inspect current keyring
pic-cli keys --write-example        # Generate starter keyring

Custom resolvers (v0.7+): As of v0.7, trust resolution is injectable and local-first. PIC no longer reloads the default keyring per signature, and custom resolvers can plug into the verifier and pipeline directly. Implement the KeyResolver protocol to use your own trust backend or preloaded trust source (HSM-backed service, Vault-managed keys, cached remote keyring, etc.):

from pic_standard import KeyResolver, StaticKeyRingResolver

Trust controls (v0.7.5+): PIC v0.7.5 introduces strict_trust mode — when enabled, all inbound provenance trust is sanitized to "untrusted" and only evidence verification can upgrade it. See docs/migration-trust-sanitization.md for migration guide.

Full guide: docs/keyring.md

---

Integrations

LangGraph

Guard any tool node with PICToolNode:

pip install "pic-standard[langgraph]"

PICToolNode now accepts verify_evidence, strict_trust, policy, and key_resolver for full pipeline configuration (v0.7.5+).

---

MCP (Model Context Protocol)

Enterprise tool guarding with fail-closed defaults, request correlation, DoS limits, and evidence sandboxing:

pip install "pic-standard[mcp]"

Full guide: docs/mcp-integration.md

---

OpenClaw

TypeScript plugin for OpenClaw AI agents (pic-gate, pic-init, pic-audit hooks):

pic-cli serve --port 7580
cd integrations/openclaw && npm install && npm run build

Full guide: docs/openclaw-integration.md

---

Cordum

Go Pack providing PIC verification as a Cordum workflow gate step with fail-closed three-way routing.

Full guide: docs/cordum-integration.md

---

HTTP Bridge (any language)

For non-Python integrations, PIC exposes an HTTP bridge:

pic-cli serve --port 3100
# POST /verify   — verify an action proposal
# GET  /health   — liveness check
# GET  /v1/version — package + protocol version

---

RFC & Prior Art

RFC-0001: PIC/1.0 — Provenance & Intent Contracts for AI Agent Action Safety

Formal specification covering scope, threat model, security properties, conformance levels, and prior art differentiation. Published as a defensive publication with a SHA-256 fingerprint manifest: docs/RFC-0001.SHA256.

Verify locally: sha256sum -c docs/RFC-0001.SHA256

---

Roadmap

• Core verifier, CLI, schema, policy system
• Evidence verification (SHA-256 hash + Ed25519 signatures)
• Anchor integrations (LangGraph, MCP, OpenClaw, Cordum)
• Injectable key resolution + hot path fix (v0.7)
• Trust hardening + attestation object draft (v0.7.5)
• Canonicalization spec (PIC Canonical JSON v1) + reference implementation (v0.8.0)
• Initial conformance suite (canonicalization + core modes) with CI runner (v0.8.0)
• Cross-implementation conformance (TypeScript/Go verifier parity)
• Normative semantics (MUST/SHOULD spec document)
• OpenAPI spec + guard hardening (structured audit logs, request correlation)
• TypeScript local verifier (second independent implementation)

---

Contributing

We welcome contributions! See CONTRIBUTING.md for how to propose changes or report issues.

We're actively seeking:

• Security researchers to stress-test causal logic
• Framework authors to build native integrations
• Enterprise architects to define domain Impact Classes

Good first contribution areas right now: conformance vectors, OpenAPI spec, TS verifier groundwork, and security review of trust sanitization behavior.

If you find PIC useful, please consider giving us a star on GitHub: it helps attract more security experts and framework authors into the community.

Issues & ideas: GitHub Issues

Maintained by @fmsalvadori   MadeInPluto