Metadata-Version: 2.5
Name: atar-trust
Version: 1.0.0a2
Summary: ATAR — Agent Trust & Attribution Root: the free, decentralized trust layer for AI agents (did:key + W3C Verifiable Credentials + signed vouches + A2A agent cards).
Project-URL: Repository, https://github.com/Dominik-8/ATAR
Project-URL: Issues, https://github.com/Dominik-8/ATAR/issues
Project-URL: Changelog, https://github.com/Dominik-8/ATAR/blob/master/CHANGELOG.md
Project-URL: Specification, https://github.com/Dominik-8/ATAR/blob/master/SPEC.md
Author: Dominik Brück
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,decentralized-identity,did,ed25519,trust,web-of-trust
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: base58
Requires-Dist: click
Requires-Dist: cryptography
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Description-Content-Type: text/markdown

# ATAR — Agent Trust & Attribution Root

> The free, decentralized **trust layer** for AI agents — the `SSL/CA` of the agent era.
> No servers. No blockchain. No cost.

[![CI](https://github.com/Dominik-8/ATAR/actions/workflows/ci.yml/badge.svg)](https://github.com/Dominik-8/ATAR/actions)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org)
[![Design: ATAR dark](https://img.shields.io/badge/design-ATAR%20dark%20%7C%20%2339ff14-neon)]

ATAR gives every AI agent a self-sovereign cryptographic identity (`did:key`, with legacy `did:agent:` support)
and lets agents vouch for one another with signed, tamper-evident attestations.
Think of it as a **passport + word-of-mouth trust network** for software agents:
anyone can verify who an agent is and who vouches for it — offline, for $0.

Transport for agents (MCP/A2A) is solved and consolidated. Trust & attribution
is the active frontier: ERC-8004, A2A signed Agent Cards, the W3C agent-identity
community work and ai-wot all attack it from different angles. ATAR's bet is to
be the **open-source trust graph with a full lifecycle** — transitive trust,
revocation, TTL and key rotation — on top of the emerging standards.

## Contents

- [Why it matters](#why-it-matters-the-top-layer-thesis)
- [Install](#install)
- [Quickstart](#quickstart)
- [How it works](#how-it-works)
- [CLI reference](#cli-reference)
- [Visual identity](#visual-identity-atar-style)
- [Project status](#project-status)
- [Honest constraints](#honest-constraints)
- [Contributing](#contributing)

## Why it matters (the "top layer" thesis)

- **Transport is solved.** MCP (tools) and A2A (agent-to-agent) are now
  consolidated under the Linux Foundation. You cannot reinvent HTTP.
- **Trust is contested, not unclaimed.** ERC-8004 puts agent reputation
  on-chain (and struggles with Sybil reviewers), A2A is adding signed Agent
  Cards, W3C community work is converging on agent identity, and ai-wot
  explores a web-of-trust. What none of them ships today is ATAR's core: a
  free, serverless trust graph with a **full lifecycle** — transitive trust
  computation, active revocation, TTL-based decay, key rotation — plus
  operator tooling (audit, watch, dashboard, export/import).
- **ATAR's angle.** Identity + vouching with zero infrastructure, as a public
  good (like HTTP): value accrues to the applications built on top
  (directories, "Know Your Agent" analytics), exactly as Google built on top
  of a free HTTP. ATAR aims to ride the standard formats, not compete with a
  fifth parallel one — see [ROADMAP.md](ROADMAP.md).

## Install

Install from PyPI:

```bash
pip install atar-trust
```

The package is `atar-trust`; the CLI command is `atar`. Current release:
`1.0.0a2` (alpha), including the did:key / W3C VC / A2A realignment.

Install from source (this is where current development lives):

```bash
git clone https://github.com/Dominik-8/ATAR.git
cd ATAR
pip install -e ".[dev]"
```

See [CHANGELOG.md](CHANGELOG.md) for what shipped and what is in flight.

## Quickstart

```bash
# 1. create two agent identities
atar keygen --name alice
atar keygen --name bob

# 2. alice vouches for bob's competence in "coding"
#    (a local name works anywhere a DID does - no copy-pasting)
atar vouch --from alice --for bob --score 0.95 --scope coding \
    --out bob-vouch.json

# 3. anyone verifies the vouch signature offline (no server, no internet)
atar verify bob-vouch.json          # -> VALID

# 4. add it to the local store so cards/dashboards/graphs can see it
atar add bob-vouch.json

# 5. build an agent card (DID + name + vouches) to present on contact
atar card --name bob --out card.json

# 6. render the Know-Your-Agent dashboard from a local trust graph
atar dashboard --seed alice --scope coding --out dash.html
```

**Real vs demo network.** `agents.toml` holds only *real running agents*
(`seed_agent` seed + `reporting_agent` cron). The larger graph in `demo.toml` is an
*illustration* — those agents are not real processes and are never in the
default bootstrap. ATAR's value is a trust layer over real agents; demo nodes
exist only to show the shape of a bigger graph.

```bash
atar bootstrap --config agents.toml   # real agents only
atar bootstrap --config demo.toml     # demo illustration, not real
```

## How it works

1. **Identity** — Ed25519 keypair; W3C `did:key` derived from the public key (legacy `did:agent:` DIDs stay importable and verifiable).
   Self-resolving, $0. Vouch *signatures* verify offline; *revocation status*
   propagates via gossip sync ([`SPEC.md`](SPEC.md) §6/§9).
2. **Vouch** — a signed attestation: *issuer vouches subject for scope@score*.
   Tamper-evident (any change invalidates the signature).
3. **ATC Carrier** — vouches encoded as header-safe tokens + an "agent card"
   JSON, presented inline over HTTP/A2A/MCP. ATAR rides *on top* of existing
   transports; it replaces nothing.
4. **Transparency graph** — vouches are content-addressed (sha256 of their
   bytes), so they can be gossiped with no operator. Each agent computes
   *transitive trust* locally from a seed of trusted roots.
5. **Revocation + Freshness + Rotation** — trust can be actively killed
   (revoke), passively expired (TTL), or recovered via key rotation. See
   [`SPEC.md`](SPEC.md) §6–§10.

See [`SPEC.md`](SPEC.md) for the full wire format and algorithms.

## CLI reference

| Command | Purpose |
|---|---|
| `atar keygen --name N` | create an agent identity, print its `did:key` |
| `atar identities` | list local identities (name -> DID; keys never shown) |
| `atar vouch --from A --for DID --score S --scope C` | create a signed vouch |
| `atar verify PATH [--max-age N]` | `VALID` / `REVOKED` / `EXPIRED` / `INVALID` |
| `atar revoke PATH` | add a vouch to the local revocation list |
| `atar add PATH` | add a vouch to the store (rejects invalid/revoked) |
| `atar list` / `atar scopes` | inspect store / list scopes + counts |
| `atar card --name N` | build an agent card (DID + vouches) |
| `atar verify-card PATH` | verify every vouch in an agent card |
| `atar graph --seed DID --scope C` | print transitive-trust ranking |
| `atar dashboard --seed DID --scope C` | render Know-Your-Agent HTML dashboard |
| `atar sync --with <peer>` / `atar auto-sync` | gossip vouches + revocations between peers (directory or `http(s)://` URL) |
| `atar peer --port 8790` | serve the local store as an HTTP gossip peer (SPEC §9.1) |
| `atar dispute <vouch> --from N --reason R` / `atar disputes` | record/list signed disputes against foreign vouches (SPEC §8.2) |
| `atar rotate --name N` | generate a new key + signed rotation statement |
| `atar reissue --name N [--commit]` | re-sign vouches under the new key (commit = +add old-revoked) |
| `atar bootstrap --config agents.toml` | reproducible agent network |
| `atar serve [--port P]` | live multi-scope dashboard (http://localhost:P) |
| `atar audit [--max-age N]` | health-check: counts valid/revoked/expired/invalid per scope |
| `atar export [--include-keys] FILE` | bundle trust graph (or full identity) to `.atpkg` |
| `atar import FILE` | restore a network bundle into the local store |
| `atar watch [--interval S] [--once]` | monitor health; alert on unhealthy transition |
| `atar issue --from N --for DID --scope S --score X [--claim C]` | issue a signed capability claim (standalone file) |
| `atar verify-claim FILE` | verify a signed capability claim (independent of store) |
| `atar vc-export F --from N` / `atar vc-verify F` | export a vouch as a W3C Verifiable Credential / verify one offline |

## Visual identity (ATAR-style)

ATAR has its own dark, corporate look - consistent and standalone.

| Token | Value | Use |
|---|---|---|
| `--bg` | `#0a0a0b` | near-black background |
| `--accent` | `#39ff14` | gift-green / neon (trust, valid, verified) |
| `--accent-dim` | `#1f7a12` | dimmed green borders/badges |
| `--accent-blue` | `#2f81f7` | GitHub-blue, for DID identifiers |
| `--text` | `#e8e8ea` | primary text |
| `--muted` | `#8a8a90` | secondary text |
| Font | Segoe UI / -apple-system | system UI stack |

The canonical tokens live in [`atar/theme.css`](atar/theme.css) — reuse them for
any ATAR UI, web page, or digest so the design stays consistent.

## Project status

| Phase | Area | Status |
|---|---|---|
| 1 | Ed25519 identity + sign/verify | ✅ |
| 2 | ATC carrier (tokens + agent cards) | ✅ |
| 3 | Transparency log + transitive trust graph | ✅ |
| 4 / 4b / 4c / 9 | ATAR is used by agents, `graph` CLI, demo network, ATC in brief | ✅ |
| 6 / 8 / 11 | Know-Your-Agent dashboard (module, CLI, live server) | ✅ |
| 7 | Persistent vouch store (file-backed, dedup) | ✅ |
| 4d / 12 | Real-agent bootstrap (CLI + `agents.toml`) | ✅ |
| 10 / 15 | Gossip (`sync`) + auto-sync hook in any agent | ✅ |
| 16 / 17 | Revocation (local + gossip) | ✅ |
| 18 | Revocation in dashboard | ✅ |
| 13 / 25 | Multi-scope dashboard (module + live server) | ✅ |
| 14 | Real agents seeded (seed_agent + reporting_agent) | ✅ |
| 20 | `atar scopes` CLI | ✅ |
| 22 | Revocation in `verify` | ✅ |
| 23 | Revocation in `add` + `sync` (defense-in-depth) | ✅ |
| 24 | Freshness / TTL (`--max-age`) | ✅ |
| 27 / 27b | Key rotation + `reissue --commit` | ✅ |
| 29 | `atar audit` CLI (trust health-check) | ✅ |
| 30 | `atar export` / `atar import` (portable `.atpkg` bundle) | ✅ |
| 31 | `atar watch` (cron-ready monitoring + ALERT) | ✅ |
| 26 | Real-agent claim issuance (`issue` / `verify-claim`) | ✅ |

All phases implemented and tested (288 tests, CI green). See
[`SPEC.md`](SPEC.md) for the authoritative protocol specification and
[`docs/test-vectors.md`](docs/test-vectors.md) for the golden
interoperability vectors every wire format is pinned against.

**Realignment Stage C shipped (2026-09-08):** HTTP gossip transport
(`atar peer`, SPEC §9.1), the CrewAI framework plugin
([docs/crewai-plugin.md](docs/crewai-plugin.md)), and score semantics +
signed disputes (SPEC §3.2/§8.2). Next: the standardization path (C4) and
wider real-agent adoption.

## Honest constraints

- **Sybil resistance is partial.** Free, serverless identity means anyone can
  mint unlimited agents. ATAR provides the *mechanism* (signed vouches);
  meaningful reputation emerges from the web-of-trust, not from the protocol.
  We do not promise Sybil-proofing — that is mathematically incompatible with
  "free + decentralized + zero-server".
- **Bootstrap needs a seed.** Adoption is the real risk. We seed ATAR by
  forcing our own agents (your primary agent) to use it, riding MCP/A2A as carriers
  rather than competing with them.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Security issues: [SECURITY.md](SECURITY.md).

## License

MIT — see [LICENSE](LICENSE).
