Metadata-Version: 2.4
Name: csae
Version: 0.2.0
Summary: Verifiable context transfer between AI agents: signed, hash-chained attestations with provenance tracking and audit logging
Author-email: Traverse Labs LLC <brett@traverselabs.ai>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/TraverseLabsLLC/CSAE
Project-URL: Documentation, https://github.com/TraverseLabsLLC/CSAE#readme
Project-URL: Issues, https://github.com/TraverseLabsLLC/CSAE/issues
Project-URL: Commercial, https://traverselabs.ai
Keywords: ai,agents,provenance,attestation,integrity,mcp,a2a
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: cryptography>=41.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# CSAE: Context State Attestation Envelope

Verifiable context transfer between AI agents across trust boundaries.

When AI agents from different vendors collaborate in regulated environments, there is no standard way to verify where context came from, whether it was altered, or what the recipient is allowed to do with it. CSAE provides cryptographically signed, hash-chained attestations with provenance tracking and tamper-evident audit logging.

## Install

```bash
pip install csae
```

Requires Python 3.9+.

## Quick start

```python
from csae.middleware import MCPAttestor

# Two agents, different vendors
agent_a = MCPAttestor(agent_id="triage-001", vendor="anthropic")
agent_b = MCPAttestor(agent_id="diagnostics-001", vendor="openai")

# Agent A attests its output
step1 = agent_a.attest("triage", {"observation": "Chest pain", "severity": "high"})

# Agent B verifies, then chains its own attestation
assert MCPAttestor.verify(step1, agent_a.public_key_pem)
step2 = agent_b.attest("diagnose", {"assessment": "Possible ACS"}, previous=step1, auto_chain=False)

# Full chain is cryptographically linked
assert step2.attestation.previous_attestation_hash == step1.chain_hash

# Tampering is detectable
step1.attestation.content["severity"] = "low"
assert not MCPAttestor.verify(step1, agent_a.public_key_pem)
```

## MCP middleware

Drop-in attestation for any MCP server. Wrap tool responses, verify incoming context, chain across multi-step workflows.

```python
from csae.middleware import MCPAttestor

server = MCPAttestor(
    agent_id="mcp-retrieval-001",
    agent_name="Data Retrieval MCP Server",
    vendor="your-org",
)

# After your MCP tool produces a result:
attested = server.attest("get_patient_record", raw_result)

# Downstream agent verifies:
MCPAttestor.verify(attested, server.public_key_pem)

# Auto-chains across sequential tool calls:
step1 = server.attest("fetch_labs", labs)
step2 = server.attest("analyze_labs", analysis)  # automatically linked to step1

# Verify an entire chain:
MCPAttestor.verify_chain([step1, step2], server.public_key_pem)

# Serialize for wire transmission:
wire_payload = attested.to_dict()  # or .to_json()
```

## Audit logging

Tamper-evident audit log with regulatory context markers. This is what you hand to an auditor.

```python
from csae.audit import AuditLog, Regulation

audit = AuditLog("./audit")

# Record with regulatory context
audit.record(attested, regulations=[Regulation.HIPAA, Regulation.EU_AI_ACT_ART12])

# Query by regulation, tool, agent, or time range
hipaa_entries = audit.query(regulation=Regulation.HIPAA)
recent = audit.query(after="2026-04-01T00:00:00Z")

# Verify no entries were modified or removed
assert audit.verify_integrity()

# Export for auditor review
audit.export_json("audit_export.json")
```

The audit log is hash-chained: modifying, deleting, or reordering any entry breaks the chain and is detectable via `verify_integrity()`.

## Why now

These are enacted laws with enforcement dates, not proposed legislation:

| Regulation | Requirement | CSAE component | Effective |
|---|---|---|---|
| EU AI Act Art. 12 | Tamper-evident logging | Integrity seal, audit log | **Aug 2026** |
| EU AI Act Art. 25 | Value chain traceability | Provenance chains | **Aug 2026** |
| HIPAA | Individual attribution in AI workflows | Authority + provenance | **May 2026** |
| FINRA 17a-3/4 | Full chain reconstruction | All components | Now |
| CA SB-942 | Machine-readable provenance | Provenance chains | Jan 2026 |
| Colorado AI Act | Impact assessments | All components | Jun 2026 |

CSAE was submitted as a candidate reference implementation to the [NIST NCCoE concept paper on AI agent identity and authorization](https://www.nccoe.nist.gov/ai/agentic-ai) (March 2026).

## How it works

Agent A processes content, computes a SHA-256 hash, and signs it with an ECDSA P-256 private key. The signed attestation travels to Agent B over any transport (MCP, A2A, HTTP, message queue). Agent B verifies the signature, confirming the content is unmodified, then creates its own attestation chained to Agent A's via the chain hash. Any auditor can verify the full chain using only the attestations and public keys, with no access to vendor internals required.

## Architecture

**Layer 0: Attestation primitive** (this library, open source). Content + provenance hash + cryptographic signature. The irreducible core.

**Layer 1: Typed provenance chains** (this library, open source). Full DAG with source types, transformation types, and per-node content hashes.

**Layer 2: Transformation metadata and authority controls.** Per-item permissions with attenuation across trust boundaries. Commercial SDK.

**Layer 3: Full CSAE envelope.** Six coupled components with integrity seal, confidence propagation tracking, degradation policies, and regulatory compliance features. Commercial SDK.

## Key management

Keys are auto-generated by default. For persistence across restarts:

```python
# Save
pem = server.private_key_pem

# Restore
server = MCPAttestor(agent_id="mcp-001", vendor="org", private_key_pem=pem)
```

## Low-level API

For direct control without the middleware layer:

```python
from csae import create_attestation, verify_attestation, generate_keypair, AgentIdentity

private_key, public_key = generate_keypair()
agent = AgentIdentity(agent_id="agent-001", vendor="your-org")

attestation = create_attestation(
    content={"observation": "Chest pain", "severity": "high"},
    provenance_hash="sha256:abc123",
    signer_agent=agent,
    private_key=private_key,
)

assert verify_attestation(attestation, public_key)
```

## Examples

See the [`examples/`](examples/) directory:

- [`mcp_middleware.py`](examples/mcp_middleware.py) -- full two-agent MCP workflow with audit logging
- [`two_agent_chain.py`](examples/two_agent_chain.py) -- minimal cross-vendor chain verification
- [`audit_log.py`](examples/audit_log.py) -- tamper-evident audit logging with regulatory markers

## Advanced features

For regulated deployments requiring full envelope integrity sealing, confidence propagation tracking, authority attenuation, and degradation under token constraints, Traverse Labs offers a commercial SDK. See [traverselabs.ai](https://traverselabs.ai) for details.

## License

Apache 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

## About

Built by [Traverse Labs LLC](https://traverselabs.ai).
