Federated Agent Web

Transport-agnostic delegation contract — reference implementation (v0.2).

This repository is the smallest credible, transport-agnostic reference implementation of the delegation contract described in MANIFESTO.md. Delegation is the protocol; Nadi, GitHub, filesystem, HTTP, A2A, queues, and future mechanisms are adapters beneath it.

• Node discovery — signed node manifests at /.well-known/faw-node.json
• Signed delegation — Ed25519-signed, JCS-canonicalized documents
• Bounded authority and budget — enforceable ceilings, deadline, expiry
• Independently verifiable terminal receipt — bound to the exact delegation
• Transport adapters — loopback/filesystem shipped; nadi_compat specified

Status

Reference implementation, laboratory prototype. Not "production-ready", not "secure", not "decentralized" — see CONFORMANCE.md for exactly what is demonstrated and SECURITY.md for the threat model. Do not run against untrusted peers.

Roadmap: v0.2 → v1.0

Quick start

Prerequisites: Git, Python 3.11 or newer, and a Bash/Zsh-compatible POSIX shell for the activation command shown below. No private keys, external services, or networked FAW peers are required.

Run the offline demo

git clone https://github.com/kimeisele/federated-agent-web.git
cd federated-agent-web

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install .

faw demo

Expected output ends with demo: OK.

Contributor installation

python -m pip install -e .
python -m pip install --group test
python -m pytest -q

Operational one-shot node

experimental / laboratory reference implementation

Persist a node, then run it as a one-shot executor or issuer against the filesystem transport:

# Create and persist a node identity
faw manifest init --name "My Node" --capabilities hash_file --out ./my-node

# Run once as executor: process one delegated task and exit
faw node run-once \
  --identity ./my-node \
  --trust ./peer-node \
  --transport-root ./transport \
  --state-dir ./state \
  --work-dir ./work \
  --role executor

# Run once as issuer: accept one terminal receipt and exit
faw node run-once \
  --identity ./my-node \
  --trust ./peer-node \
  --transport-root ./transport \
  --state-dir ./state \
  --work-dir ./work \
  --role issuer

The same one-shot runner can use the experimental Nadi/GitHub adapter without changing FAW documents, verification, replay, execution, or receipts:

faw node run-once \
  --identity ./executor --trust ./issuer \
  --transport nadi-github \
  --transport-root ./state/nadi-transport \
  --nadi-hub-repo owner/relay-repository \
  --nadi-relay-address executor-mailbox \
  --nadi-route urn:faw:issuer-node=issuer-mailbox \
  --state-dir ./state/executor --work-dir ./work/executor \
  --role executor

--nadi-route maps signed FAW identities to untrusted relay addresses and is repeatable. GitHub credentials come from the caller's existing gh login; do not put credentials in routes or FAW documents. See docs/ADAPTER_NADI.md for the trust boundary.

Each invocation processes at most one inbound envelope and exits. State is persisted across restarts (replay store, pending-delegation store). hash_file is the only executable capability. No daemon, no HTTP server, no endless loop.

Repository layout

MANIFESTO.md            the manifesto (Draft 3), imported verbatim
SPEC.md                 normative contract summary (v0.2)
CONFORMANCE.md          what is proven, and how
SECURITY.md             threat model and security invariants
skill.md                agent-readable onboarding file (read-only by default)
schemas/                three normative JSON Schemas (closed, v0.2)
src/federated_agent_web/
  canonical.py          strict RFC 8785 (JCS) parse + canonicalization
  crypto.py             Ed25519 signing/verification, kid derivation
  identity.py           stable node identity, rotatable keys, manifest chains
  documents.py          envelope, schema validation, document builders
  verify.py             the authoritative 11-step verification procedure
  replay.py             receiver-side at-most-once admission store
  pending.py            issuer-side outstanding-delegation store
  cli.py                the `faw` CLI
  transports/           transport interface + filesystem adapter
examples/run_demo.py    offline two-node demo entry point
vectors/                golden vectors for independent implementations
docs/                   reuse report, implementation report, Nadi adapter spec

Verify public evidence

python -m pip install -e .
faw evidence verify examples/evidence-bundle

This verifies a historical signed delegation and receipt using only committed public keys. No private keys or network access are required. It does not assert current admissibility or that a third-party operator accepted the receipt.

The contract in one paragraph

A node publishes a signed manifest declaring capabilities, endpoints, keys, cost class, and rate limits. A caller issues a signed delegation carrying a stable task_id, a unique attempt_id, a named capability, structured authority, an enforceable budget, and a deadline. The receiver verifies the document in a fixed order (strict JCS parse → schema → audience → temporal → pinned manifest chain → freshness → signature → replay → authority → atomic admission) and admits each attempt at most once. Every attempt ends in exactly one terminal receipt (succeeded / failed / rejected / timed_out) signed by the executor and bound to the delegation digest; the issuer accepts it only against its own outstanding-delegation store.

License

MIT. See SECURITY.md before exposing any node to a network.