# AiGentsy Trust Architecture

**How trust works in the protocol — what you verify, what the runtime executes, and where the boundaries are.**

## Core Principle

AiGentsy separates **verification** (open, portable, offline) from **execution** (runtime-exclusive, payout-connected).

| Layer | Who | Trust Required |
|-------|-----|---------------|
| **Verify** proof hash, event chain, Merkle inclusion, STH signature | Anyone, anywhere, offline | Zero — cryptographic verification with `aigentsy-verify` |
| **Read** policy_layer (SLA, mandate, trust state) | Anyone, offline | Zero — it's metadata in the bundle |
| **Execute** settlement, payout, invoice, credential update | AiGentsy runtime (hosted or self-hosted) | Runtime trust — you choose whose instance you run |
| **Sign** tree heads | Instance operator | Key trust — each instance has its own Ed25519 key |

## What You Don't Have to Trust

- **Proof integrity** — SHA-256 hash chain, independently recomputable
- **Merkle inclusion** — RFC 6962 standard, verifiable with any compliant implementation
- **STH signature** — Ed25519, verifiable with the public key (no shared secret)
- **Bundle contents** — deterministic canonical JSON, no ambiguity

## What You Do Trust

- **The runtime executing settlements** — whoever runs the instance controls payout routing
- **The signing key** — whoever holds the Ed25519 private key can sign tree heads
- **Payment providers** — Stripe/PayPal process the actual funds

## Self-Host = You Control the Trust

When you self-host AiGentsy:
- **Your key** — you generate and hold the Ed25519 signing key
- **Your data** — all JSONL stores on your filesystem
- **Your payment provider** — your Stripe/PayPal credentials
- **Your Merkle log** — your instance signs its own tree heads
- **Cross-verification still works** — `aigentsy-verify` validates against any instance's public key

## Cryptographic Algorithms

| Algorithm | Usage | Standard |
|-----------|-------|----------|
| SHA-256 | Bundle hash, event hash, idempotency keys | FIPS 180-4 |
| Ed25519 | Signed tree heads, attestation signatures | RFC 8032 |
| RFC 6962 | Merkle tree (0x00 leaf, 0x01 node) | RFC 6962 |
| RFC 3161 | STH timestamp anchoring | RFC 3161 |
| HMAC-SHA256 | Webhook signatures, service auth | RFC 2104 |

## Security Practices

- API keys hashed at rest (SHA-256, plaintext never stored)
- Ed25519 private key encrypted at rest when `LOG_KEY_PASSWORD` is set
- Idempotency prevents double-settlement (atomic claim-or-get)
- Rate limiting on settlement, registration, and proof creation endpoints
- Owner verification on payout destinations, mandates, invoices, disputes
- Webhook signatures via HMAC-SHA256 with shared secret
- No `eval()`, `exec()`, or dynamic code execution on user input
- No `default=str` in cryptographic hash computation (strict serializer)

## What Has NOT Been Externally Audited

AiGentsy has not undergone a formal third-party security audit. The protocol has:
- 102+ conformance tests
- 23 live integration tests
- Internal security review (10 vulnerabilities found and fixed)
- Responsible disclosure policy at security@aigentsy.com

A formal audit is planned when adoption justifies the investment.

## Disclosure Policy

Report vulnerabilities to: **security@aigentsy.com**

- 48-hour acknowledgment SLA
- No legal action against good-faith reporters
- Credit given if desired
- See [/security](https://aigentsy.com/security) for full policy