Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
update docs
Antonio Ojea9a2e7a238af0
diff --git a/README.md b/README.mdindex a8a03573..a71e6eb8 100644--- a/README.md+++ b/README.md@@ -1,88 +1,73 @@# SAM: Sovereign Agent Mesh-SAM is a zero-trust, pure P2P networking layer for autonomous agents.+SAM is a minimal libp2p-based mesh with two binaries:-It is built for environments where centralized gateways and centralized trust are a liability. Agents discover each other over libp2p DHT, authenticate with passport biscuits, authorize capabilities with Biscuit caveats, and communicate directly over A2A streams.+- `sam-hub`: OIDC bridge + Biscuit issuer + connection gater+- `sam-node`: node identity/login flow + mesh node runtime-## Why SAM+The current repository intentionally focuses on basic functionality and testability.-- Pure P2P: no API gateway in the data path-- Zero-trust by default: every call is authenticated and authorized-- Isolated mesh namespace: separate SAM protocol space and storage scope-- Auditability: inspect tokens/cards and dry-run key flows--## Quick Start--### Build+## Build```bashmake build-./bin/sam-agent --help+./bin/sam-node --help./bin/sam-hub --help```-### Run tests+## Basic Usage++### 1. Run the hub```bash-make test-make test-e2e+SAM_OIDC_ISSUER=https://issuer.example.com \+SAM_OIDC_ID=sam-client \+SAM_OIDC_SECRET=sam-secret \+SAM_HUB_KEY=$(openssl rand -hex 32) \+./bin/sam-hub```-### First workflow+### 2. Login a node```bash-# Authenticate-sam-agent identity login --hub https://identity.example.com+./bin/sam-node login --hub http://localhost:8080+```-# Publish an agent capability-sam-agent publish --skill risk-audit --mcp-port 8080+This prints a login URL. After authenticating in browser, paste the returned biscuit token back into the CLI prompt.-# Call by capability-sam-agent call risk-audit --message "audit this report"+### 3. Run a node-# Inspect credential artifacts-sam-agent inspect biscuit "vendor-bot;allow_skill=risk-audit"+```bash+./bin/sam-node run```-## Documentation+Or pass a token directly:-- Docs site: https://aojea.github.io/sam-- Manifesto: https://aojea.github.io/sam/#/README.md-- User journey (dark mesh): https://aojea.github.io/sam/#/guides/dark-mesh.md-- Hub as rendezvous point: https://aojea.github.io/sam/#/guides/hub-rendezvous.md-- CLI reference: https://aojea.github.io/sam/#/cli/reference.md-- Testing guide: https://aojea.github.io/sam/#/testing.md--## Architecture--SAM keeps control at the edge: discovery is federated, trust is verified locally, and execution stays peer-to-peer.--```mermaid-flowchart LR- A[Agent A / Caller] -->|Discover capability| DHT[(Federated DHT\n/sam/fed/<id>)]- DHT -->|Peer candidates| A- A -->|A2A stream + Vouch + Biscuit| B[Agent B / Callee]- B -->|Federation Gate\nverify vouch + peer identity| G[AuthZ Layer]- G -->|BiscuitSkillGate\nallow_skill(c)| E[MCP Resource / Skill]- E -->|Result| B- B -->|A2A response| A+```bash+./bin/sam-node run --token <identity-biscuit>```-Trust flow summary:+## Testing-- Discovery: agents find peers by capability in an isolated federation namespace.-- Authentication: callee verifies caller identity with a locally trusted vouch.-- Authorization: Biscuit caveats constrain which capability can be executed.-- Execution: skill runs locally through the agent backend (JSON-RPC) and the response returns over A2A.+```bash+make test+make test-e2e+make test-e2e-container+```++`test-e2e-container` runs a containerized BATS framework that starts:-## Development+- a mock OIDC container+- a `sam-hub` container+- multiple `sam-node` containers-Key make targets:+## Documentation-- `make build`-- `make test`-- `make test-e2e`-- `make lint`+- Docs index: `docs/index.html`+- Project docs landing page: `docs/README.md`+- Quickstart: `docs/quickstart.md`+- CLI reference: `docs/cli/reference.md`+- Testing guide: `docs/testing.md`## Licensediff --git a/docs/DOCUMENTATION.md b/docs/DOCUMENTATION.mddeleted file mode 100644index 0e361ed3..00000000--- a/docs/DOCUMENTATION.md+++ /dev/null@@ -1,354 +0,0 @@-# SAM Documentation - Complete Inventory--## π Documentation Structure--Generated comprehensive Docsify documentation for Sovereign Agent Mesh (SAM).--### Root Level (`docs/`)--```-docs/-βββ index.html β‘ Docsify configuration + plugins-βββ _coverpage.md π¨ Landing page with SAM pitch-βββ _sidebar.md π Navigation sidebar-βββ README.md π Main manifesto (Trust Desert problem)-βββ quickstart.md β‘ 5-minute quick start-βββ faq.md β Frequently asked questions-βββ glossary.md π Terminology reference-βββ testing.md π§ͺ Testing guide (BATS, Go, integration)-βββ contributing.md π€ Contributor's guide-```--### Guides (`docs/guides/`)--```-guides/-βββ dark-mesh.md π Enterprise dark mesh walkthrough-β - Scenario: Acme Corp with 3 business units-β - Full CLI snippets for federation setup-β - Step-by-step: create federation β login β publish β call β audit-β - Explains Biscuit tokens, federation isolation, transparency-```--### CLI Reference (`docs/cli/`)--```-cli/-βββ reference.md π₯οΈ Complete kubectl-style command hierarchy-β - sam identity (login, whoami)-β - sam publish (quick, card, mcp)-β - sam call (with Biscuit auth)-β - sam inspect (biscuit, card)-β - sam mesh (federations, agents)-β - sam up (persistent node)-β - Global flags and dry-run philosophy-β - Patterns and best practices-```--### Concepts (`docs/concepts/`)--```-concepts/-βββ federation.md π’ Federation & storage deep dive-β - Physical isolation via bbolt per federation-β - Why no central database (honeypot problem)-β - Federation initialization and vouch system-β - Disaster recovery-β-βββ identity.md π Identity & vouch system-β - Vouch-based identity (works offline)-β - Why this solves central authority problem-β - Vouch vs Token vs Signature-β - Multi-federation identity-β - PeerID derivation (deterministic)-β-βββ biscuit.md π« Biscuit authorization-β - Plain-text Biscuits (why not cryptographic)-β - Authorization flow-β - Parsing and skill gates-β - A2A stream handling-β - Use cases and inspection-β-βββ a2a-protocol.md π Agent-to-Agent protocol-β - Connection setup and message structure-β - Authentication (vouch) + Authorization (Biscuit)-β - Error codes and stream lifecycle-β - Network considerations-β - Code examples for server and client-```-------## π Documentation Breakdown--### Page Counts & Content--| Document | Lines | Focus |-|----------|-------|-------|-| README.md (Manifesto) | 250+ | Philosophy, problem statement, architecture overview |-| dark-mesh.md (User Guide) | 400+ | Step-by-step scenario walkthrough with CLI examples |-| cli/reference.md | 350+ | Complete command documentation |-| federation.md (Concepts) | 350+ | Storage architecture, bbolt, multi-tenant design |-| identity.md (Concepts) | 300+ | Cryptographic identity, vouch, decentralization |-| biscuit.md (Concepts) | 300+ | Skill-based authorization, caveats, enforcement |-| a2a-protocol.md (Concepts) | 300+ | Protocol details, authentication, code examples |-| testing.md (Testing) | 250+ | Unit/integration/E2E testing guide |-| contributing.md (Contributing) | 250+ | Development setup, code style, submission workflow |-| faq.md (FAQ) | 200+ | 30+ common questions answered |-| glossary.md (Glossary) | 150+ | 50+ terms + acronyms |-| quickstart.md (Quick Ref) | 100+ | 5-minute reference card |--**Total Documentation**: ~3,500+ lines of comprehensive, reader-friendly content-------## π― Key Features--### 1. **Docsify Setup** (index.html)-- β Dark mode theme (Sovereign look)-- β Search plugin for full-text search-- β Sidebar navigation auto-generated from _sidebar.md-- β Copy-to-clipboard buttons on all code blocks-- β Footer with license and copyright-- β Responsive design (mobile + desktop)-- β Syntax highlighting (Bash, Go, JSON)--### 2. **Cover Page** (_coverpage.md)-- β Eye-catching logo (β‘ emoji)-- β Tagline: "Zero-Trust Networking for the Agentic Era"-- β Key value props (Pure P2P, Zero-Trust, Federation-Ready, Audit-First)-- β Problem statement (Trust Desert)-- β Links to documentation and GitHub--### 3. **Manifesto** (README.md)-- β Core philosophy: "Sovereign" agents, "Engineering Truth"-- β The Trust Desert problem (gateways, IdP, audit)-- β How SAM solves it (Pure P2P, Zero-Trust, Passport auth, Audit)-- β Architecture overview with data flow diagrams-- β Why "Sovereign"-- β What SAM does NOT do (blockchain, sidecar, etc.)--### 4. **User Journey** (dark-mesh.md)-- β Real-world scenario (Acme Corp with 3 business units)-- β 9 step-by-step sections with CLI snippets-- β Shows mesh namespace scoping-- β Explains identity gating (passport verification)-- β Demonstrates Biscuit tokens (skill restrictions)-- β Audit transparency (sam inspect commands)-- β Trust flow diagram--### 5. **CLI Reference** (cli/reference.md)-- β kubectl-style command hierarchy-- β Global node/runtime flags and command-specific options-- β All commands documented (identity, publish, call, inspect, mesh, up)-- β Flags and examples for each command-- β Dry-run philosophy explained-- β Patterns and best practices-- β Output formats (JSON + text)--### 6. **Technical Concepts** (concepts/)-- β Mesh storage: bbolt architecture and default namespace behavior-- β Identity: passport biscuit system-- β Biscuit: authorization model, skill gating, enforcement-- β A2A Protocol: message structure, authentication flow, code examples--### 7. **Testing Guide** (testing.md)-- β Three-level testing: unit, integration, E2E-- β BATS syntax and examples-- β Linux namespace isolation (CLONE_NEWNET)-- β Test framework helpers-- β Running test suite locally-- β Performance testing (benchmarks)-- β Debugging techniques--### 8. **Contributing** (contributing.md)-- β Development setup (prerequisites, clone, build)-- β Code style (Go conventions, file organization)-- β Testing requirements-- β Commit message format-- β PR workflow-- β Common tasks (new CLI command, new protocol feature)-- β Code review checklist--### 9. **FAQ** (faq.md)-- β 30+ questions organized by category-- β Getting started (install, publish, call)-- β Core concepts (mesh namespace, passport, Biscuit, A2A)-- β Architecture & design (why P2P, why not OAuth)-- β Network & connectivity (NAT, firewall, cloud)-- β Security & trust (production readiness, key management)-- β Performance (scalability, latency)-- β Operations & troubleshooting-- β Integration (libraries, Docker)-- β Roadmap & future work--### 10. **Glossary** (glossary.md)-- β 50+ terms (A-Z)-- β Clear, concise definitions-- β Acronym quick reference-- β Cross-references to related concepts--### 11. **Quick Start** (quickstart.md)-- β 5-minute setup-- β Common commands cheat sheet-- β File locations-- β Troubleshooting table-- β Key concepts summary-- β Documentation links-------## π¨ Design Principles--### Tone: "Engineering Truth"-- β Clear, direct explanations-- β No marketing fluff-- β Focus on how things work, not hype-- β Explain trade-offs explicitly--### Audience: Developer-First-- β Code examples in Go, Bash, JSON-- β CLI-first (SAM is primarily a CLI)-- β Architecture diagrams and data flows-- β Link to implementation (test files, source)--### Structure: Layered-- β Quick Start β User Guide β Deep Dive β Reference-- β Beginner can read dark-mesh.md, get productive-- β Expert can read concepts/, understand internals-- β Operator has reference.md for commands-------## π How to Use--### Serve Documentation Locally--```bash-# Install Docsify CLI-npm install -g docsify-cli--# Serve docs-cd docs-docsify serve .--# Open browser to http://localhost:3000-```--### Build for Production--```bash-# Use GitHub Pages-# Push docs/ folder to repository-# Enable GitHub Pages in Settings--# Or host on any static site:-# - Netlify-# - Vercel-# - AWS S3 + CloudFront-# - Traditional web server-```--### Extend Documentation--1. **Add a new guide**: Create `docs/guides/<name>.md`-2. **Add a CLI command**: Document in `docs/cli/reference.md`-3. **Add a concept**: Create `docs/concepts/<name>.md`-4. **Update sidebar**: Edit `docs/_sidebar.md`-5. **Update search**: Docsify auto-indexes all .md files-------## π Content Summary by Category--### π― For Users-- **Quick Start** (quickstart.md): Get running in 5 minutes-- **User Guide** (guides/dark-mesh.md): Enterprise scenario walkthrough-- **CLI Reference** (cli/reference.md): All commands + examples-- **FAQ** (faq.md): Answers to common questions--### π§ For Developers-- **Contributing** (contributing.md): Development setup + workflow-- **Testing** (testing.md): How to write and run tests-- **Concepts** (concepts/): Technical deep dives-- **A2A Protocol** (concepts/a2a-protocol.md): Code examples--### π For Architects-- **Manifesto** (README.md): Philosophy + design principles-- **Federation** (concepts/federation.md): Storage architecture-- **Identity** (concepts/identity.md): Cryptography + trust model-- **Biscuit** (concepts/biscuit.md): Authorization design--### π For Support-- **FAQ** (faq.md): Troubleshooting section-- **Glossary** (glossary.md): Terminology-- **Contributing** (contributing.md): How to report bugs-------## β Quality Checklist--- β **Comprehensive**: Every major feature documented-- β **Current**: Matches latest code (publish.go, call.go, inspect.go)-- β **Auditable**: Explains --dry-run and sam inspect-- β **Clear**: No jargon; explains terms on first use-- β **Actionable**: Code examples work (tested with binary)-- β **Linked**: Cross-references between docs-- β **Styled**: Docsify dark theme with custom colors-- β **Searchable**: Full-text search enabled-- β **Accessible**: Mobile-friendly, readable fonts-------## π Documentation Statistics--| Metric | Value |-|--------|-------|-| Total documents | 15 |-| Total lines | 3,500+ |-| Code examples | 50+ |-| Diagrams/ASCII art | 10+ |-| Cross-references | 100+ |-| Search terms | 500+ |-| Supported languages | 3 (Bash, Go, JSON) |-| Mobile responsive | Yes |-| Dark mode | Yes |-| Copy-to-clipboard | Yes |-------## π― Next Steps--1. **Serve locally**: `docsify serve docs/` (requires npm)-2. **Deploy to GitHub Pages**: Push to main branch-3. **Customize**: Edit index.html theme colors-4. **Extend**: Add more concepts/guides as needed-5. **Share**: Link to docs in README, GitHub pages-------## π Files Created--```-β docs/index.html-β docs/_coverpage.md-β docs/_sidebar.md-β docs/README.md-β docs/quickstart.md-β docs/faq.md-β docs/glossary.md-β docs/testing.md-β docs/contributing.md-β docs/guides/dark-mesh.md-β docs/cli/reference.md-β docs/concepts/federation.md-β docs/concepts/identity.md-β docs/concepts/biscuit.md-β docs/concepts/a2a-protocol.md-```--**Total: 15 documentation files**-------Ready to share SAM with the world! πdiff --git a/docs/README.md b/docs/README.mdindex 5211f96a..434fcf1a 100644--- a/docs/README.md+++ b/docs/README.md@@ -1,182 +1,27 @@-# Sovereign Agent Mesh: The Manifesto+# SAM Documentation-## What is SAM?+This repository currently provides a minimal SAM runtime with two binaries:-**Sovereign Agent Mesh (SAM)** is a **zero-trust networking layer for autonomous agents**. It enables agents to discover, authenticate, and collaborate with each otherβwithout centralized gateways, identity providers, or trust intermediaries.+- `sam-hub`: OIDC bridge and identity biscuit issuer+- `sam-node`: mesh node CLI with login and run commands-SAM is built on two core principles:+The documentation here is intentionally small and aligned with what is implemented today.-1. **Pure P2P Architecture**: No gateways. Agents communicate directly using libp2p, with routing through DHT and relays.-2. **Zero-Trust at the Edge**: Cryptographic identity is verified locally, not delegated to a central authority.+## What Works Today-## The Trust Desert Problem+1. Build and run `sam-node` and `sam-hub`+2. Perform node login via hub OIDC flow+3. Persist identity in local node store+4. Run long-lived hub and node processes+5. Run local and containerized BATS tests-Today's agentic systems operate in a **trust desert**:+## Start Here-### The Gateway Trap-- Agents talk to a central API gateway, which becomes a **single point of failure**-- The gateway sees all traffic (privacy nightmare)-- If the gateway is compromised, all agents are compromised-- Scaling requires more gateways (distributed trust problem unsolved)+- [Quick Start](quickstart.md)+- [CLI Reference](cli/reference.md)+- [Testing](testing.md)-### The Identity Provider Trap-- Agents rely on a central identity provider for credentials-- If the IdP is breached, all agents lose their identity-- The IdP becomes a **trusted third party** that must always be trusted-- Offline operation is impossible+## Notes-### The Audit Nightmare-- Audit trails are controlled by the infrastructure operator-- No transparency into what data is flowing where-- Security teams have to trust the operator's logs-- Compliance becomes a matter of faith, not engineering--## How SAM Solves This--### 1. Pure P2P (No Gateways)-```-Traditional: Agent A β Gateway β Agent B-SAM: Agent A β Agent B (direct, with DHT discovery)-```--Agents discover each other through a **federated DHT**:-- Discovery happens via `/sam` namespace (public) or `/sam/fed/<id>` (isolated)-- Connections are direct (or relayed through libp2p DCUtR if NAT'd)-- The DHT is the *only* intermediateβand it's read-only for discovery--### 2. Zero-Trust Identity (No Central Authority)-```-Traditional: Agent A requests token from IdP β IdP validates β Agent A uses token-SAM: Agent A proves identity via Ed25519 vouch β Agent B verifies locally-```--Every agent has a **cryptographic identity**:-- Ed25519 keypair (libp2p standard)-- Vouch from a federation (stored in bbolt, not fetched from a server)-- Peer ID derived directly from the key (no token, no revocation server)--Agent B verifies Agent A's identity by:-1. Checking if Agent A's Peer ID is in the federation's vouch database-2. Verifying the signature on the A2A message matches the Peer ID-3. No external lookup required--### 3. Federation Isolation (Enterprise Dark Mesh)-Enterprises often need **isolated networks** with their own governance rules:--```-Federation Alpha: Agents operate in /sam/fed/alpha namespace-Federation Beta: Agents operate in /sam/fed/beta namespace-Public Mesh: Agents operate in /sam namespace--Result: Agents in Alpha cannot discover agents in Beta (network isolation)-```--Isolation is enforced at the DHT level:-- Each federation has its own `dht.ProtocolPrefix("/sam/fed/<id>")`-- A2A gating checks federation membership before handshake-- Storage is federated (one bbolt database per federation)--### 4. Skill-Based Authorization (Zero-Trust for Capabilities)-Even within a federation, not all agents can access all skills:--```-Alice publishes a Biscuit token: "bob;allow_skill=weather-bot,chat"-Alice calls Bob with the token: Bob verifies "weather-bot" is in allowed_skills-Result: Bob rejects any other capability-```--Biscuit tokens are lightweight caveats:-- Format: `<subject>;<caveat>=<value>`-- Parsed and validated locally (no external verification)-- Example: `alice;allow_skill=risk-audit,email-send`--### 5. Audit Transparency (sam inspect & --dry-run)-Every operation can be audited **before** it executes:--```bash-# Inspect a Biscuit token-sam inspect biscuit "alice;allow_skill=weather-bot"--# Preview an Agent Card without publishing-sam publish --skill weather-bot --mcp-port 8080 --dry-run=client--# Validate a call request without network-sam call bob --message "hello" --dry-run=client--# Decode an Agent Card JSON-sam inspect card '{"peer_id":"...", ...}'-```--All request/response shapes are exposed for security auditing.--## Architecture at a Glance--### Components--| Component | Purpose | Tech |-|-----------|---------|------|-| **libp2p Node** | P2P networking, DHT, relays | libp2p-go |-| **Federated DHT** | Isolated discovery per federation | dht.ProtocolPrefix |-| **bbolt Storage** | Distributed, consensus-free vouch DB | go.etcd.io/bbolt |-| **A2A Service** | Agent-to-agent RPC over libp2p streams | /sam/a2a/1.0 |-| **Federation Gate** | Identity verification before A2A | VouchGate |-| **Biscuit Gate** | Skill-based authorization | BiscuitSkillGate |-| **Discovery Service** | Capability-based peer lookup | DiscoveryService |-| **Agent Card** | Signed manifest of agent capabilities | protocol.AgentCard |--### Data Flow: A2A Call--```-Agent A DHT (Discovery) Agent B- β β β- ββ sam call weather-bot β β- ββ Discover peers for capabilityβββΌβββ /sam/fed/alpha β- ββ Select Agent B β ββββββββββββββββββββββββββ β- β β- ββ Connect to Agent B on /sam/a2a/1.0 βββββββββββββββββββββββββββ- β β- ββ Send Vouch + Biscuit ββββββββββββββββββββββββββββββββββββββββ FederationGate- β ββ Check vouch- ββ Send A2A request ββββββββββββββββββββββββββββββββββββββββββββ BiscuitGate- β ββ Verify skill- β β ββ Task Response βββββββββββββ€ Execute- β β- ββ Return result to CLI β-```--## Why "Sovereign"?--An agent is **sovereign** when it:-- Controls its own identity (not assigned by a central authority)-- Can operate without external services (no IdP, no gateway)-- Can form agreements with other agents (federation, vouches)-- Can prove its capabilities cryptographically (Agent Card, Biscuit)--SAM enables this sovereignty by moving trust from **authorities** to **cryptography**.--## What SAM Does NOT Do--- **SAM is not a blockchain**: No distributed consensus, no ledger-- **SAM is not a service mesh sidecar**: Agents link SAM directly, not via a sidecar-- **SAM is not OAuth/OIDC**: No tokens issued by a central authority-- **SAM is not a VPN**: No tunnel mode, direct P2P connections-- **SAM is not a replacement for TLS**: We use TLS for transport, libp2p handles the rest--## Next Steps--- **[Getting Started](guides/dark-mesh.md)**: Set up an enterprise dark mesh-- **[CLI Reference](cli/reference.md)**: Full kubectl-style command hierarchy-- **[Technical Deep Dive](concepts/federation.md)**: How federation isolation works-- **[Testing Guide](testing.md)**: Run the test suite locally--## Philosophy--SAM is built on **engineering truth**, not marketing claims:--- We show how the system works, not hide complexity-- We expose request/response shapes for auditing-- We use standard crypto (Ed25519, libp2p) not custom protocols-- We measure performance (not claim it)-- We test everything (unit, integration, E2E)--The goal is **trustworthy systems**, not trust-based systems.+- Older architecture and feature-heavy docs were removed to avoid drift.+- If a feature is not documented here, assume it is not part of the current minimal scope.diff --git a/docs/_coverpage.md b/docs/_coverpage.mddeleted file mode 100644index 4cc016cb..00000000--- a/docs/_coverpage.md+++ /dev/null@@ -1,39 +0,0 @@---# Sovereign Agent Mesh--> Zero-Trust Networking for the Agentic Era--- **Pure P2P**: No gateways, no central coordinators-- **Zero-Trust**: Cryptographic identity at the edge, not centralized authorities-- **Federation-Ready**: Isolated namespaces for enterprise dark meshes-- **Audit-First**: Built-in transparency for security compliance--[Documentation](#/README.md)-[GitHub](https://github.com/aojea/sam)-[Getting Started](#/quickstart.md)-------## The Trust Desert Problem--In today's agentic systems, agents operate in a **trust desert**:--- **Gateways** become honeypots (central points of failure)-- **Centralized identity** providers can be breached or compromised-- **Network isolation** is difficult without expensive VPNs or custom infrastructure-- **Audit trails** are either missing or controlled by the infrastructure operator--SAM (Sovereign Agent Mesh) solves this by bringing **Zero-Trust principles to autonomous agents**.--## Engineering Truth--This is not marketing. SAM is built on proven principles:--1. **Cryptographic Identity**: Ed25519 keys derived from libp2p, not reliant on central authorities-2. **Federated DHT**: Isolated discovery namespaces (`/sam/fed/<id>`) prevent cross-federation discovery-3. **Identity Gating**: bbolt vouch database ensures peer identity before A2A handshake-4. **Skill-Based Authorization**: Biscuit tokens with caveats enforce fine-grained access control-5. **Transparent Auditing**: `sam inspect` and `--dry-run` modes expose all request/response shapes--No gateways. No magic. Just cryptography and networking.diff --git a/docs/_sidebar.md b/docs/_sidebar.mdindex d9811447..857d0fb2 100644--- a/docs/_sidebar.md+++ b/docs/_sidebar.md@@ -1,28 +1,5 @@-<!-- Sidebar Navigation -->--- **Getting Started**- - [Overview](#/README.md)- - [Quick Start](#/quickstart.md)- - [Enterprise Dark Mesh](#/guides/dark-mesh.md)- - [Hybrid Intelligence Audit](#/guides/hybrid-intelligence.md)--- **CLI Reference**- - [Command Hierarchy](#/cli/reference.md)--- **Technical Concepts**- - [Federation & Storage](#/concepts/federation.md)- - [Identity & Vouch System](#/concepts/identity.md)- - [Biscuit Authorization](#/concepts/biscuit.md)- - [A2A Protocol](#/concepts/a2a-protocol.md)--- **Testing**- - [Testing Guide](#/testing.md)--- **Contributing**- - [Contributing Guide](#/contributing.md)--- **Resources**- - [FAQ](#/faq.md)- - [Glossary](#/glossary.md)- - [Documentation Inventory](#/DOCUMENTATION.md)- - [License](https://github.com/aojea/sam/blob/main/LICENSE)+- [Overview](#/README.md)+- [Quick Start](#/quickstart.md)+- [CLI Reference](#/cli/reference.md)+- [Testing](#/testing.md)+- [License](https://github.com/aojea/sam/blob/main/LICENSE)diff --git a/docs/cli/reference.md b/docs/cli/reference.mdindex 22f45a60..d037d76a 100644--- a/docs/cli/reference.md+++ b/docs/cli/reference.md@@ -1,169 +1,72 @@-# SAM CLI Reference+# CLI Reference-SAM uses a kubectl-style command hierarchy with shared node/runtime flags.+The current repository exposes two CLIs:-## Global Flags+- `sam-node`+- `sam-hub`-Most commands accept these shared flags:--| Flag | Type | Default | Description |-|------|------|---------|-------------|-| `--listen` | stringSlice | `/ip4/0.0.0.0/udp/0/quic-v1` | libp2p listen multiaddrs |-| `--bootstrap` | stringSlice | empty | bootstrap peer multiaddrs |-| `--dht-mode` | string | `client` | DHT mode: `client`, `server`, `auto` |-| `--relay-service` | bool | `false` | enable relay service |-| `--user-agent` | string | `sam/0.1.0` | libp2p user-agent |-| `--run-for` | duration | `0` | optional duration before graceful shutdown |-| `--hub` | string | empty | OIDC hub URL for identity login/passport issuance |-| `--identity` | string | empty | PEM-encoded Ed25519 private key path |-| `--debug` | bool | `false` | enable debug logging |--## sam-agent identity--Authentication and credential management.--### sam-agent identity login--Authenticate with the hub using device flow and store credentials plus passport biscuit locally.+## sam-node```bash-sam-agent identity login --hub https://identity.acme.corp+sam-node --help```-### sam-agent identity whoami+### sam-node login-Show current authenticated identity.+Start the login flow and persist identity biscuit in the local store.```bash-sam-agent identity whoami+sam-node login --hub http://localhost:8080```-## sam-agent publish--Publish an agent card to DHT namespaces.+Flags:-### Quick Mode+- `--hub`: hub base URL (default `http://localhost:8080`)-```bash-sam-agent publish --skill risk-audit --mcp-port 8080-```--Useful flags:-- `--skill` or repeatable `--capability`-- `--mcp-port`-- `--republish-every`-- `--dry-run=client|server`-- `--resource-name`, `--resource-kind`, `--resource-endpoint`, `--resource-description`+### sam-node run-### sam-agent publish card+Start the mesh node.```bash-sam-agent publish card --file agent-card.json --republish-every 5m+sam-node run```-### sam-agent publish mcp--```bash-sam-agent publish mcp --port 8080 --name "Risk Audit Tool"-```+Flags:-## sam-agent call+- `--token`: identity biscuit override (if omitted, load from local store)+- `--listen`: repeatable libp2p listen addresses-Execute an A2A task against a remote agent.+Examples:```bash-sam-agent call risk-audit --message "Audit the Q1 risk report"+sam-node run --token <identity-biscuit>+sam-node run --listen /ip4/0.0.0.0/udp/5001/quic-v1 --listen /ip4/0.0.0.0/tcp/5002```-Useful flags:-- `--message`-- `--biscuit`-- `--timeout`-- `--amount`, `--asset`, `--nonce`-- `--dry-run=client|server`--## sam-agent proxy--Start a local HTTP proxy that tunnels over SAM.+## sam-hub```bash-sam-agent proxy --port 8081+sam-hub --help```-Useful flags:-- `--port`-- `--target-header`-- `--biscuit`-- `--timeout`--## sam-agent inspect+`sam-hub` runs the OIDC bridge, issues identity biscuits, and gates unauthenticated peers.-Decode local artifacts for auditing.+Flags:-### sam-agent inspect biscuit--```bash-sam-agent inspect biscuit "alice;allow_skill=risk-audit,weather-bot"-```+- `--issuer`: OIDC issuer URL+- `--client-id`: OIDC client ID+- `--client-secret`: OIDC client secret+- `--key`: 32-byte hex seed used to derive Ed25519 biscuit signing key+- `--listen`: repeatable libp2p listen addresses+- `--mesh`: mesh name+- `--public-url`: public callback base URL-### sam-agent inspect card+Example:```bash-sam-agent inspect card '{"peer_id":"...","agent_card":{...}}'+sam-hub \+ --issuer https://issuer.example.com \+ --client-id sam-client \+ --client-secret sam-secret \+ --key $(openssl rand -hex 32)```--## sam-agent mesh--Mesh visibility commands.--### sam-agent mesh get agents--```bash-sam-agent mesh get agents-sam-agent mesh get agents --capability risk-audit-sam-agent mesh get agents --watch -o json-```--## sam-agent up--Start a SAM node and wait for shutdown.--```bash-sam-agent up \- --listen /ip4/0.0.0.0/udp/4001/quic-v1 \- --bootstrap /ip4/192.168.1.100/udp/4001/quic-v1/p2p/12D3KooXA7cBj4VKrpv7HzKLmvnWKLVqZZHJm9NyN6Td3Y4hMWjK-```--## Patterns--### Publish workflow--```bash-# Preview card locally-sam-agent publish --skill new-capability --mcp-port 9000 --dry-run=client--# Publish to mesh-sam-agent publish --skill new-capability --mcp-port 9000-```--### Call workflow with Biscuit--```bash-TOKEN="partner-bot;allow_skill=risk-audit"-sam-agent inspect biscuit "$TOKEN"-sam-agent call risk-audit --biscuit "$TOKEN" --message "Check compliance"-```--## Dry-Run Philosophy--Dry-run modes support audit transparency and safe rollout:--- `--dry-run=client`: build and validate payloads locally, no network activity-- `--dry-run=server`: initialize runtime, skip final network commit--Use these to preview behavior, capture JSON artifacts for security review, and gate CI checks.--## Next Steps--- **[User Journey Guide](#/guides/dark-mesh.md)**: scenario walkthrough-- **[FAQ](#/faq.md)**: troubleshooting and operational tipsdiff --git a/docs/concepts/a2a-protocol.md b/docs/concepts/a2a-protocol.mddeleted file mode 100644index cfc0c7ab..00000000--- a/docs/concepts/a2a-protocol.md+++ /dev/null@@ -1,418 +0,0 @@-# A2A Protocol: Agent-to-Agent Communication--## Overview--The **A2A (Agent-to-Agent)** protocol is how agents call skills offered by other agents in a federation.--- **Transport**: libp2p streams (TLS-encrypted)-- **Port/Namespace**: `/sam/a2a/1.0`-- **Message Format**: JSON-RPC 2.0 task envelope-- **Authentication**: Vouch (federation membership)-- **Authorization**: Biscuit token (skill access)-------## Protocol Flow--### Connection Setup--```-Client Server- β β- ββ Open libp2p stream β- β /sam/a2a/1.0 β- ββββββββββββββββββββββββββββββ>β- β β- β<βββββββββββββββββββββββββββββ β Stream open-```--### A2A Request--```json-{- "jsonrpc": "2.0",- "id": "call-123",- "method": "message",- "params": {- "message": "Get weather forecast for Seattle"- },- "headers": {- "x-vouch": "<vouch JSON>",- "x-biscuit": "alice;allow_skill=weather-bot",- "x-payment": {- "amount": 1,- "asset": "sam-credit",- "nonce": "1713451200000000000",- "capability": "weather-bot"- }- }-}-```--### A2A Response--```json-{- "jsonrpc": "2.0",- "id": "call-123",- "result": {- "forecast": "Partly cloudy, 65Β°F"- }-}-```-------## Message Structure--### Headers--| Header | Type | Required | Purpose |-|--------|------|----------|---------|-| `x-vouch` | JSON | Yes | Proves federation membership |-| `x-biscuit` | string | No | Grants access to specific skills |-| `x-payment` | JSON | No | Micropayment info (future) |--### Request (JSON-RPC 2.0)--```json-{- "jsonrpc": "2.0", // Protocol version- "id": "string", // Request ID (echo in response)- "method": "message", // Always "message" (A2A task request)- "params": { // task parameters- "message": "..." // Natural-language prompt- }-}-```--### Response (JSON-RPC 2.0)--Success:-```json-{- "jsonrpc": "2.0",- "id": "call-123",- "result": {- "response": "..."- }-}-```--Error:-```json-{- "jsonrpc": "2.0",- "id": "call-123",- "error": {- "code": -32600,- "message": "Invalid request",- "data": {- "details": "..."- }- }-}-```-------## Authentication & Authorization--### Step 1: Authentication (Vouch)--Server receives request with vouch header.--```-vouch = {- "subject": "alice",- "peer_id": "12D3Koo...",- "federation": "finance",- "issued_at": "2026-04-18",- "expires_at": "2027-04-18",- "signature": "..."-}--Server checks:-1. Is vouch signed by a trusted hub?-2. Is vouch expired?-3. Is peer_id in federation vouch database?--If all pass β Proceed to authorization-If any fail β Return error-```--### Step 2: Authorization (Biscuit)--Server checks if caller is allowed the requested skill.--```-biscuit = "alice;allow_skill=weather-bot,risk-audit"--Server checks:-1. Parse biscuit: allowed_skills = ["weather-bot", "risk-audit"]-2. Is requested_skill in allowed_skills?--If yes β Execute skill-If no β Return ErrSkillNotAllowed-```--### Step 3: Execution--Server calls the local agent backend with the skill request.--```-POST http://127.0.0.1:8080-Body: {- "jsonrpc": "2.0",- "method": "message",- "params": {- "message": "Get forecast"- }-}--Response: {- "result": {...}-}--Server returns response to client-```-------## Error Codes--### A2A Errors--| Code | Reason |-|------|--------|-| `-32600` | Invalid request (malformed JSON) |-| `-32601` | Capability not found |-| `-32603` | Internal server error |--### SAM-Specific Errors--| Error | Cause | Solution |-|-------|-------|----------|-| `ErrNotInFederation` | Vouch not in federation | Authenticate: `sam-agent identity login --hub <url>` |-| `ErrVouchExpired` | Vouch timestamp > expiry | Re-authenticate: `sam-agent identity login --hub <url>` |-| `ErrSkillNotAllowed` | Skill not in Biscuit caveats | Get new Biscuit with skill, or ask for permission |-| `ErrBackendFailed` | Local backend error | Check local backend logs |-------## Lifespan--### Request-Response Cycle--```-1. Client dials /sam/a2a/1.0 stream-2. Client sends vouch header-3. Server validates vouch (FederationGate)-4. Client sends biscuit header + skill request-5. Server validates biscuit (BiscuitSkillGate)-6. Server executes skill (calls local backend)-7. Server sends response-8. Stream closes-```--### Timeout--Default: 20 seconds (configurable with `--timeout`)--```bash-sam-agent call mycapability --timeout 30s-```-------## Code Example: Server--```go-// A2A service handler-func (s *A2AService) handleStream(stream libp2pnet.Stream) error {- ctx := context.Background()- defer stream.Close()-- // 1. Read vouch from headers- vouchJSON := stream.Header("x-vouch")-- // 2. Parse vouch- vouch, err := parseVouch(vouchJSON)- if err != nil {- return fmt.Errorf("parsing vouch: %w", err)- }-- // 3. Authenticate (Federation Gate)- peerID := stream.Conn().RemotePeer()- capability := getCapabilityFromRequest(stream)-- if err := s.gate.Allow(ctx, peerID, capability); err != nil {- return fmt.Errorf("federation gate: %w", err)- }-- // 4. Read biscuit from headers- biscuitToken := stream.Header("x-biscuit")-- // 5. Authorize (Biscuit Gate)- if s.skillGate != nil {- if err := s.skillGate.CheckSkill(ctx, biscuitToken, capability); err != nil {- return fmt.Errorf("skill gate: %w", err)- }- }-- // 6. Read request body- var req protocol.A2ARequest- if err := json.NewDecoder(stream).Decode(&req); err != nil {- return fmt.Errorf("decoding request: %w", err)- }-- // 7. Execute skill (call local backend)- resp, err := s.executeBackend(ctx, capability, req.Params)- if err != nil {- return fmt.Errorf("executing skill: %w", err)- }-- // 8. Send response- return json.NewEncoder(stream).Encode(resp)-}-```--### Code Example: Client--```go-// A2A call from client-func callRemoteSkill(ctx context.Context, host host.Host, target peer.ID, skill string) error {- // 1. Open stream- stream, err := host.NewStream(ctx, target, "/sam/a2a/1.0")- if err != nil {- return fmt.Errorf("opening stream: %w", err)- }- defer stream.Close()-- // 2. Get local vouch- vouch, err := loadLocalVouch()- if err != nil {- return err- }-- // 3. Create biscuit token- biscuit := "alice;allow_skill=" + skill-- // 4. Build request- req := &A2ARequest{- JSONRPC: "2.0",- ID: "call-123",- Method: "message",- Params: map[string]interface{}{- "message": "Execute skill",- },- }-- // 5. Send headers- stream.SetHeader("x-vouch", mustMarshal(vouch))- stream.SetHeader("x-biscuit", biscuit)-- // 6. Send request- if err := json.NewEncoder(stream).Encode(req); err != nil {- return fmt.Errorf("sending request: %w", err)- }-- // 7. Read response- var resp A2AResponse- if err := json.NewDecoder(stream).Decode(&resp); err != nil {- return fmt.Errorf("reading response: %w", err)- }-- if resp.Error != nil {- return fmt.Errorf("A2A error: %v", resp.Error)- }-- return nil-}-```-------## Stream Lifecycle--### TCP-like Semantics--A2A streams behave like TCP connections:-- **Connect**: Open stream to remote peer-- **Send**: Write request JSON-- **Receive**: Read response JSON-- **Close**: Stream closes after response--### Multiple Calls--To make multiple calls efficiently:-```go-// Open connection once-stream, err := host.NewStream(ctx, target, "/sam/a2a/1.0")--// Make multiple calls on same stream (future feature)-// Currently: one call per stream-```-------## Network Considerations--### Bandwidth--A2A requests are lightweight:-- Request: ~200 bytes (JSON-RPC header + small prompt)-- Response: Variable (depends on result size)--### Latency--Typical A2A call latency:-- DHT discovery: 500ms - 5s (cached after first call)-- Stream setup: 50-200ms-- RPC roundtrip: 100-500ms-- Backend execution: 1-10s (depends on implementation)-- **Total**: 2-15 seconds--### Firewalls--If direct connection fails, libp2p automatically:-1. Attempts hole-punch (DCUtR)-2. Falls back to relay-3. Stream still works (just slower)-------## Future Enhancements--1. **Streaming Responses**: For large result sets-2. **Batch Requests**: Multiple calls in one stream-3. **Subscribe Pattern**: Stream-based subscriptions (not request-response)-4. **Compression**: Gzip compression for large payloads-5. **Signature**: Sign requests with client key (not just vouch)-------## Specification Status--**Current**: Implemented in Go, tested with BATS and integration tests--**Future**: Standardize as IETF RFC or similar--**Stability**: Protocol is stable; APIs may change before v1.0-------## Related Concepts--- **[Vouch](#/concepts/identity.md)**: Authentication mechanism-- **[Biscuit](#/concepts/biscuit.md)**: Authorization mechanism-- **[Federation](#/concepts/federation.md)**: Network isolation-- **[CLI](#/cli/reference.md)**: How to invoke A2A calls-------## Next Steps--- **[Try it Out](#/guides/dark-mesh.md)**: Make your first A2A call-- **[Integration Tests](https://github.com/aojea/sam/tree/main/tests/integration)**: See A2A in action-- **[Contributing](#/contributing.md)**: Help improve the protocoldiff --git a/docs/concepts/biscuit.md b/docs/concepts/biscuit.mddeleted file mode 100644index 99d4bb3a..00000000--- a/docs/concepts/biscuit.md+++ /dev/null@@ -1,489 +0,0 @@-# Biscuit Authorization: Fine-Grained Access Control--## The Problem: All-or-Nothing Access--Traditional systems either grant full access or none:--```-Partner API Key: alice-key-123-βββ Can call ANY endpoint-βββ No granular access control--Issue: If the key leaks, attacker gets full access-```--SAM uses **Biscuit tokens** to grant access to specific skills only.-------## What is a Biscuit Token?--A Biscuit is a **lightweight credential with caveats** (restrictions).--### Format--```-<subject>;<caveat>=<value>,<value>-```--### Example--```-alice;allow_skill=weather-bot-```--Breakdown:-- **Subject**: `alice` (who the token is for)-- **Caveat**: `allow_skill` (what type of restriction)-- **Values**: `weather-bot` (specific skills allowed)--### Multiple Skills--```-alice;allow_skill=weather-bot,risk-audit,email-send-```--Allows: weather-bot, risk-audit, email-send-Denies: everything else--### No Skills (Unrestricted)--```-alice-```--No caveat = full access to all skills-------## Why Plain Text?--SAM uses plain-text Biscuits instead of cryptographic ones because:--1. **Transparency**: Anyone can read what permissions are granted-2. **Auditability**: `sam inspect biscuit` decodes without a server-3. **Lightweight**: No cryptography overhead for authorization-4. **Revocable**: Just delete the token from the app--**Trade-off:** Plain-text Biscuits can be modified by the client, but SAM assumes:-- Client trusts their own OS (local isolation)-- Tokens are shared only with trusted applications-- Server can verify trust via A2A authentication first-------## Authorization Flow--### Step 1: Grant Access--Alice creates a Biscuit for partner-bot:--```bash-TOKEN="[email protected];allow_skill=risk-audit"-# Shared via secure channel (email, encrypted message, etc)-```--### Step 2: Client Uses Token--Partner-bot calls alice's agent:--```bash-sam-agent call risk-audit \- --biscuit "[email protected];allow_skill=risk-audit" \- --message "Audit my data"-```--### Step 3: Server Verifies--Alice's agent:--1. Receives the Biscuit token-2. Parses it: `ParsedBiscuit{Subject: "partner-bot", AllowedSkills: ["risk-audit"]}`-3. Checks: Is `risk-audit` in `AllowedSkills`?-4. **Yes** β Execute skill-5. **No** β Reject with `ErrSkillNotAllowed`--### Step 4: Enforce Fine-Grained Access--Partner-bot tries to use a different skill:--```bash-sam-agent call compliance-check \- --biscuit "[email protected];allow_skill=risk-audit" \- --message "Check compliance"-```--Alice's agent:--1. Parses token: `AllowedSkills: ["risk-audit"]`-2. Checks: Is `compliance-check` in `AllowedSkills`?-3. **No** β Return error: `ErrSkillNotAllowed`-------## Biscuit Parsing--### SimpleB iscuitParser--SAM uses a simple parser that handles plain-text Biscuits:--```go-type SimpleBiscuitParser struct {}--func (p *SimpleBiscuitParser) Parse(ctx context.Context, token string) (*ParsedBiscuit, error) {- // Format: subject;allow_skill=skill1,skill2,...-- parts := strings.Split(token, ";")-- biscuit := &ParsedBiscuit{- Subject: strings.TrimSpace(parts[0]),- AllowedSkills: []string{},- }-- if len(parts) < 2 {- return biscuit, nil // No caveat = unrestricted- }-- // Parse caveat: allow_skill=skill1,skill2- caveatParts := strings.Split(parts[1], "=")- if caveatParts[0] != "allow_skill" {- return nil, ErrUnknownCaveat- }-- skills := strings.Split(caveatParts[1], ",")- for _, skill := range skills {- if s := strings.TrimSpace(skill); s != "" {- biscuit.AllowedSkills = append(biscuit.AllowedSkills, s)- }- }-- return biscuit, nil-}-```--### ParsedBiscuit Structure--```go-type ParsedBiscuit struct {- Subject string // "alice"- AllowedSkills []string // ["weather-bot", "risk-audit"]-}-```-------## Skill Gate: Enforcement--When a call arrives, the **BiscuitSkillGate** enforces the caveat:--```go-type BiscuitSkillGate struct {- parser BiscuitParser-}--func (g *BiscuitSkillGate) CheckSkill(ctx context.Context, token string, skill string) error {- parsed, err := g.parser.Parse(ctx, token)- if err != nil {- return err- }-- // If no skills are restricted, allow all- if len(parsed.AllowedSkills) == 0 {- return nil- }-- // Check if requested skill is allowed- for _, allowed := range parsed.AllowedSkills {- if allowed == skill {- return nil- }- }-- return ErrSkillNotAllowed-}-```-------## A2A Stream Handling with Biscuit--When a call arrives on the A2A stream:--```go-func (s *A2AService) handleStream(stream libp2pnet.Stream) error {- peerID := stream.Conn().RemotePeer()-- // 1. Federation Gate: Check vouch (authentication)- if err := s.gate.Allow(ctx, peerID, capability); err != nil {- return fmt.Errorf("federation gate: %w", err)- }-- // 2. Read Biscuit token from stream headers- biscuitToken := stream.Header("x-biscuit")-- // 3. Biscuit Gate: Check skill (authorization)- if s.skillGate != nil {- if err := s.skillGate.CheckSkill(ctx, biscuitToken, capability); err != nil {- return fmt.Errorf("skill gate: %w", err)- }- }-- // 4. Execute the skill- return s.executeSkill(ctx, capability, payload)-}-```-------## Use Cases--### Use Case 1: Partner Access (Read-Only)--```bash-# Grant vendor access to audit skill only-VENDOR_TOKEN="[email protected];allow_skill=audit"--# Vendor can use this skill-sam call audit --biscuit "$VENDOR_TOKEN"--# Vendor cannot use other skills-sam call delete-data --biscuit "$VENDOR_TOKEN" # β Error: skill not allowed-```--### Use Case 2: Multiple Skills (Limited Scope)--```bash-# Grant contractor access to specific tools-CONTRACTOR_TOKEN="[email protected];allow_skill=log-query,metric-check"--# Contractor can use these-sam call log-query --biscuit "$CONTRACTOR_TOKEN" # β OK-sam call metric-check --biscuit "$CONTRACTOR_TOKEN" # β OK--# Contractor cannot use others-sam call deploy --biscuit "$CONTRACTOR_TOKEN" # β Error: not in allow list-```--### Use Case 3: Unrestricted Token (Trusted Partner)--```bash-# Grant trusted partner full access (no caveat)-PARTNER_TOKEN="[email protected]"--# Partner can use ANY skill-sam call risk-audit --biscuit "$PARTNER_TOKEN" # β OK-sam call weather --biscuit "$PARTNER_TOKEN" # β OK-sam call deploy --biscuit "$PARTNER_TOKEN" # β OK (all allowed)-```-------## Inspecting Tokens--Before sharing a token, verify what it grants:--### Single Skill--```bash-sam inspect biscuit "alice;allow_skill=weather-bot"-```--Output:-```-Biscuit Token Analysis-======================--Subject: alice-Allowed Skills: weather-bot--Human-Readable Summary:-This token issued to 'alice' allows execution of 'weather-bot' skill only.-```--### Multiple Skills--```bash-sam inspect biscuit "partner;allow_skill=risk-audit,compliance-check"-```--Output:-```-Biscuit Token Analysis-======================--Subject: partner-Allowed Skills:- - risk-audit- - compliance-check--Human-Readable Summary:-This token issued to 'partner' allows execution of 2 skills:-risk-audit, compliance-check.-```--### Unrestricted--```bash-sam inspect biscuit "trusted-partner"-```--Output:-```-Biscuit Token Analysis-======================--Subject: trusted-partner-Allowed Skills: (none, unrestricted)--Human-Readable Summary:-This token issued to 'trusted-partner' allows execution of ALL skills.-```-------## Token Management--### Creating Tokens--Tokens are not generated by a server; they're created locally:--```bash-# CLI (future): Create a token-sam economy biscuit create \- --subject "[email protected]" \- --allow-skill risk-audit \- --allow-skill weather-bot-```--Or manually:-```bash-TOKEN="[email protected];allow_skill=risk-audit,weather-bot"-```--### Sharing Tokens--Tokens should be shared via secure channels:-- Encrypted email-- Secure messaging app-- In-person (QR code)-- Not in logs, not in URLs, not in Git--### Revoking Tokens--Tokens are revoked by **removing them from use**:--```bash-# In your application configuration-echo "[email protected];allow_skill=risk-audit" > revoked-tokens.txt-```--Then check against revoked list before allowing:--```go-if isRevoked(token) {- return ErrTokenRevoked-}-```--### Token Lifetime--By default, Biscuits have **no expiry**. To implement expiry:--1. Add an optional caveat: `alice;allow_skill=weather-bot;expires=2027-04-18`-2. Check expiry in the gate: `CheckSkill()` validates expiry-3. Revoke after expiry-------## Limitations and Future Work--### Current Limitations--1. **Plain-text**: Client can modify token (mitigated by OS isolation)-2. **No signature**: Server trusts client's assertion (mitigated by A2A auth first)-3. **No expiry**: Tokens don't auto-expire (revoke manually)-4. **No delegation**: Can't delegate further ("partner gives token to sub-partner")--### Future Enhancements--1. **Cryptographic Biscuits**: Sign tokens with issuer key-2. **Expiry Caveats**: `allow_skill=X;expires=<timestamp>`-3. **Delegation**: Allow `partner` to grant subsets to others-4. **Revocation List**: Server-side revocation (traded for offline capability)-------## Integration with A2A Protocol--### Request Flow--```-Client Server- β β- ββ Connect A2A stream β- ββββββββββββββββββββββββββββββ>β- β β- ββ Send Vouch (authentication) β- ββββββββββββββββββββββββββββββ>β- β β- ββ Send Biscuit (authorization)β- ββββββββββββββββββββββββββββββ>β- β β- β [FederationGate checks] β- β [BiscuitSkillGate checks] β- β β- β [Execute]β- β β- β<βββββββββββββββββββββββββββββ β Response-```--### Code Example--```go-// Client prepares call-vouch := loadVouch(federation)-biscuit := "partner;allow_skill=risk-audit"-capability := "risk-audit"--// Server validates-gate := NewVouchGate(store)-if err := gate.Allow(ctx, peerID, capability); err != nil {- return err // Not in federation-}--skillGate := NewBiscuitSkillGate(parser)-if err := skillGate.CheckSkill(ctx, biscuit, capability); err != nil {- return err // Not in allowed_skills-}--// Execute-return executeSkill(ctx, capability, payload)-```-------## Security Considerations--### Trust Assumptions--1. **Client OS is secure**: Tokens are stored in plaintext-2. **Client network is secure**: Tokens sent over libp2p TLS-3. **Server trusts A2A authentication first**: Biscuit is secondary check-4. **Tokens are not long-lived**: Regular rotation recommended--### Attack Scenarios--| Scenario | Risk | Mitigation |-|----------|------|-----------|-| Token leaked | Attacker uses skill | Revoke token, re-authenticate |-| Client compromised | Attacker modifies token | OS isolation, encryption |-| Server compromised | Attacker sees skills | Caveats are read-only, don't leak secrets |-| Token replayed | Attacker reuses token | Signature + nonce (future) |-------## Next Steps--- **[Identity & Vouch System](#/concepts/identity.md)**: How authentication works-- **[A2A Protocol](#/concepts/a2a-protocol.md)**: How authorization is enforced-- **[CLI Reference](#/cli/reference.md)**: `sam inspect biscuit` usagediff --git a/docs/concepts/federation.md b/docs/concepts/federation.mddeleted file mode 100644index dbc09ff3..00000000--- a/docs/concepts/federation.md+++ /dev/null@@ -1,393 +0,0 @@-# Federation & Storage: Physical Isolation--## The Problem: Shared Trust Infrastructure--Traditional agent systems use a **single central database**:--```-Gateway/Database-βββ Org A agents-βββ Org B agents-βββ Org C agents--Issue: All organizations trust the same infrastructure operator.-Risk: If the database is breached, all organizations are compromised.-```--SAM solves this with **federated, isolated storage**.-------## The Solution: bbolt per Federation--Each federation has its own **independent database**:--```-Finance Federation Operations Federation-~/.config/sam/federations/ ~/.config/sam/federations/- βββ finance.db βββ operations.db- βββ identities βββ identities- βββ vouches βββ vouches- βββ reputation βββ reputation- βββ cache βββ cache-```--**Key benefits:**--1. **Physical separation**: Data is not shared between federations-2. **Independent backups**: Each federation can back up its own DB-3. **Compliance isolation**: Finance data never touches Operations storage-4. **No trusted intermediary**: Each federation manages its own identities-------## How Federation Storage Works--### Storage Layout--```-~/.config/sam/-βββ identity/-β βββ keystore.json (personal Ed25519 key)-β βββ vouch.json (cached vouch from hub)-β βββ credentials.keyring (encrypted passwords)-β-βββ federations/- βββ finance.db (bbolt database)- βββ operations.db (bbolt database)- βββ public.db (default federation)-```--### bbolt Structure (per federation)--Each `.db` file is a bbolt database with buckets:--```-finance.db-βββ identities-β βββ alice.smith β {peerID, created, updated}-β βββ bob.jones β {peerID, created, updated}-β βββ ...-β-βββ vouches-β βββ 12D3KooXA7cB... β {subject, federation, issued, expires}-β βββ 12D3KooXdef456... β {subject, federation, issued, expires}-β βββ ...-β-βββ reputation-β βββ alice.smith β {trust_score, calls_completed, failed}-β βββ ...-β-βββ cache- βββ peer_addrs- βββ capability_index- βββ ...-```--**Bucket purposes:**--| Bucket | Purpose | Example |-|--------|---------|---------|-| `identities` | Map subjects to PeerIDs | alice.smith β 12D3Koo... |-| `vouches` | Cached vouch credentials | 12D3Koo... β {issued, expires, federation} |-| `reputation` | Trust scores and call history | alice.smith β {score: 95, calls: 42} |-| `cache` | Temporary peer addresses, capability index | weather-bot β [12D3Koo..., 12D3Koo...] |-------## Federation Initialization--When you create a federation:--```bash-sam-agent up-```--SAM:-1. Generates a deterministic federation ID from the name: `fed-abc123...` (sha256 of "finance")-2. Creates `~/.config/sam/federations/finance.db`-3. Initializes buckets: `identities`, `vouches`, `reputation`, `cache`-4. Stores federation metadata (name, ID, created_at)--```-$ cat ~/.config/sam/federations/finance.db- (binary bbolt file)-```--The federation ID is deterministic, so re-creating a federation with the same name yields the same ID (useful for recovery).-------## Identity Vouch System--When an agent authenticates with a federation hub:--```bash-sam-agent identity login --hub https://identity.acme.corp-```--### Step 1: Hub Issues Vouch--The hub (identity server) issues a signed voucher:--```json-{- "subject": "[email protected]",- "federation": "finance",- "peer_id": "12D3KooXA7cBj4VKrpv7HzKLmvnWKLVqZZHJm9NyN6Td3Y4hMWjK",- "issued_at": "2026-04-18T10:00:00Z",- "expires_at": "2027-04-18T10:00:00Z",- "signature": "..." (hub's Ed25519 signature)-}-```--### Step 2: Local Cache--SAM stores the vouch in bbolt:--```-finance.db/vouches/12D3KooXA7cBj4VKrpv7HzKLmvnWKLVqZZHJm9NyN6Td3Y4hMWjK β {- subject: "[email protected]",- federation: "finance",- issued_at: 2026-04-18T10:00:00Z,- expires_at: 2027-04-18T10:00:00Z-}-```--### Step 3: Verification Without Server--When alice.smith publishes an agent or calls another agent, SAM:--1. Extracts the vouch from bbolt (no server needed)-2. Verifies the signature using the hub's public key (cached locally)-3. Checks expiry: is `now < expires_at`?-4. Allows the operation if valid--**Key insight:** The hub is **only contacted once** (at login). All subsequent operations use the cached vouch.-------## Why No Central Database?--### Traditional Approach (Honeypot)-```-All agents β Central DB β Security team--Issue 1: If DB is breached, all agents are compromised-Issue 2: DB operator must be trusted forever-Issue 3: Scaling requires replicating the trust-```--### SAM Approach (Federated)-```-Finance agents β Finance.db (Finance org controls)-Operations agents β Operations.db (Ops org controls)-Partner agents β Partner.db (Partner org controls)--Benefit 1: Finance breach doesn't expose Operations-Benefit 2: Each org controls its own trust-Benefit 3: Federations can operate independently-```-------## Federation Isolation at DHT Level--Storage is isolated, and **DHT discovery is also isolated**:--### Finance Federation-```bash-sam-agent publish --skill risk-audit --mcp-port 8080-```--DHT announcement:-```-Namespace: /sam/fed/finance-PeerID: 12D3KooXA7cBj4VKrpv7HzKLmvnWKLVqZZHJm9NyN6Td3Y4hMWjK-Skill: risk-audit-```--### Operations Federation-```bash-sam-agent publish --skill incident-response --mcp-port 8090-```--DHT announcement:-```-Namespace: /sam/fed/operations-PeerID: 12D3KooXdef456...-Skill: incident-response-```--### Discovery Results--Finance agent queries:-```bash-sam-agent call risk-audit-```--Result: Finds only agents in `/sam/fed/finance` (risk-audit skill)--Operations agent queries:-```bash-sam-agent call risk-audit-```--Result: Finds nothing (risk-audit not published in operations namespace)--**Physical separation + DHT isolation = true isolation**-------## Vouch vs Token vs Signature--These three concepts work together:--| Concept | Purpose | Scope | Lifetime |-|---------|---------|-------|----------|-| **Vouch** | Proves identity to federation | Federation-specific | Long (1 year) |-| **Biscuit Token** | Grants skill access | Ad-hoc | Short or unlimited |-| **Signature** | Proves cryptographic ownership | Message-specific | Single message |--### Example Flow--```-1. Alice logs in β Gets vouch for "finance" federation- βββ Vouch stored in ~/.config/sam/federations/finance.db- βββ Valid for 1 year--2. Alice publishes agent β Signs Agent Card with Ed25519 key- βββ Signature proves Alice owns the card- βββ Signature is part of the card--3. Alice grants partner access β Creates Biscuit token- βββ "partner-bot;allow_skill=risk-audit"- βββ Shared via secure channel- βββ No expiry (revoke by removing from app)--4. Partner calls Alice's agent- βββ Partner sends vouch (proves they're in the federation)- βββ Partner sends Biscuit token (proves they can access risk-audit)- βββ Alice verifies both β Executes- βββ Alice returns signed response-```-------## Managing Multiple Federations--An agent can participate in multiple federations:--```bash-# Alice is in finance federation-sam-agent identity login --hub https://identity.acme.corp--# Alice is also invited to operations (different hub)-sam-agent identity login --hub https://ops-identity.acme.corp--# Alice publishes to both-sam-agent publish --skill risk-audit --mcp-port 8080-sam-agent publish --skill audit-log --mcp-port 8090--# Each federation has its own storage-~/.config/sam/federations/finance.db-~/.config/sam/federations/operations.db-```--Each federation database:-- Stores its own set of identity vouches-- Publishes to its own DHT namespace-- Has separate reputation scores-------## Disaster Recovery--### Backing Up a Federation--```bash-# Backup federation DB-cp ~/.config/sam/federations/finance.db ~/backups/finance.db.backup--# Backup identity credentials-cp ~/.config/sam/identity/ ~/backups/identity.backup-```--### Restoring a Federation--```bash-# Restore from backup-cp ~/backups/finance.db.backup ~/.config/sam/federations/finance.db--# Agent will continue with cached vouch-sam-agent call risk-audit-```--If the vouch is stale, re-authenticate:-```bash-sam-agent identity login --hub https://identity.acme.corp-```-------## Performance: Why bbolt?--**bbolt is chosen because:**--1. **ACID transactions**: Consistent reads/writes-2. **Single file**: No distributed consensus needed-3. **Fast**: B+ tree structure, in-process-4. **No external dependencies**: Pure Go, no server--**Alternative approaches we rejected:**--- **SQLite**: Requires SQL schema, more complex-- **Redis**: Requires central server (defeats isolation)-- **DynamoDB/PostgreSQL**: Vendor lock-in, centralized-- **In-memory map**: No persistence across restarts--bbolt gives us **federated isolation + local performance**.-------## Storage Layout Example (Acme Corp)--```-Acme Corp IT-βββ ~/.config/sam/- βββ identity/- β βββ keystore.json (Alice's Ed25519 key)- β βββ vouch.json (Alice's vouch for "finance")- β- βββ federations/- βββ finance.db (Finance federation)- β βββ identities: {alice β 12D3Koo...}- β βββ vouches: {12D3Koo... β {subject: alice, ...}}- β βββ reputation: {alice β {score: 98}}- β βββ cache: {risk-audit β [12D3Koo...]}- β- βββ operations.db (Ops federation)- β βββ identities: {bob β 12D3Koo...}- β βββ vouches: {12D3Koo... β {subject: bob, ...}}- β βββ reputation: {bob β {score: 87}}- β βββ cache: {incident-response β [12D3Koo...]}- β- βββ public.db (Default federation)- βββ identities: {...}- βββ vouches: {...}- βββ cache: {...}--Federated Database Architecture:-- Finance.db is owned by Finance org-- Operations.db is owned by Ops org-- No shared database-- No central trust-```-------## Next Steps--- **[Identity & Vouch System](#/concepts/identity.md)**: Deep dive into how identity works-- **[Biscuit Authorization](#/concepts/biscuit.md)**: How skill-based access control works-- **[A2A Protocol](#/concepts/a2a-protocol.md)**: How agents authenticate and call each otherdiff --git a/docs/concepts/identity.md b/docs/concepts/identity.mddeleted file mode 100644index 48b25181..00000000--- a/docs/concepts/identity.md+++ /dev/null@@ -1,432 +0,0 @@-# Identity & Vouch System: Decentralized Credentials--## The Central Authority Problem--Traditional systems use a **central identity provider**:--```-All agents β OAuth/OIDC Server β Decide who is allowed--Issues:-1. The IdP must always be available (unavailable = no agents work)-2. The IdP sees all authentication attempts (privacy risk)-3. If compromised, all agents lose identity-4. Offline operation is impossible-```--SAM solves this with **vouch-based identity** that works offline.-------## How Vouch-Based Identity Works--### Phase 1: Authentication (Online, One-Time)--```bash-sam-agent identity login --hub https://identity.acme.corp-```--**What happens:**--1. User provides username/password-2. SAM sends credentials to the hub-3. Hub verifies credentials (LDAP, database, whatever)-4. Hub issues a **Vouch** (signed JSON)-5. Vouch is cached locally in bbolt-6. Hub is no longer needed--**Vouch structure:**--```json-{- "subject": "[email protected]",- "peer_id": "12D3KooXA7cBj4VKrpv7HzKLmvnWKLVqZZHJm9NyN6Td3Y4hMWjK",- "federation": "finance",- "issued_at": "2026-04-18T10:00:00Z",- "expires_at": "2027-04-18T10:00:00Z",- "signature": "abcdef... (hub's Ed25519 signature)"-}-```--### Phase 2: Offline Authorization (No Server)--After login, Alice can operate completely offline:--```bash-# Alice publishes an agent (no network)-sam-agent publish --skill risk-audit --mcp-port 8080--# Alice calls another agent (peer-to-peer only)-sam-agent call weather-bot --message "forecast"-```--**Behind the scenes:**--1. Alice's agent sends the cached vouch to Bob's agent-2. Bob's agent:- - Extracts the hub's public key from the vouch- - Verifies the signature (locally, cryptographically)- - Checks if the vouch is expired- - If valid, trusts the vouch-3. No network request to the hub--**Trust chain:**--```-Hub issued vouch β Hub's signature on vouch- β-Alice's agent stores vouch in bbolt- β-Bob's agent receives vouch- β-Bob's agent verifies hub's signature (public key known)- β-Bob trusts Alice (because Bob trusts the hub)-```-------## Why This Works Without a Central Authority--The key insight: **Trust the issuer's signature, not the current state of a server.**--### Traditional Approach (Stateful)-```-Agent A asks: "Is Alice still authorized?"- β-IdP Server: "Let me check... yes, still authorized"- β-Agent A trusts response--Problem: IdP must always have the answer-```--### SAM Approach (Cryptographic)-```-Agent A receives: "Alice issued by Hub on 2026-04-18, expires 2027-04-18, signed by Hub"-Agent A verifies: Hub's signature matches public key- β-Agent A trusts vouch (if not expired)--Benefit: No server needed, offline works, Hub could disappear-```-------## Vouch Expiry and Renewal--Vouches have a limited lifetime (typically 1 year):--```json-{- "subject": "alice.smith",- "issued_at": "2026-04-18T10:00:00Z",- "expires_at": "2027-04-18T10:00:00Z"-}-```--When the vouch expires:--```bash-sam call risk-audit --message "hello"-```--Error:-```-Error: stored identity vouch is expired; run login again-```--Re-authenticate:-```bash-sam identity login --hub https://identity.acme.corp-```--SAM:-1. Contacts hub (online required for renewal)-2. Verifies credentials again-3. Gets new vouch-4. Caches it (good for another year)-------## Vouch vs Token vs Signature--SAM uses three layers of cryptography:--### Layer 1: Vouch (Identity)-**Purpose:** Prove you are who you say you are--```-"Alice is [email protected], issued by acme.corp hub on 2026-04-18"-(signed by hub)--Lifetime: 1 year-Usage: Authentication (am I in the federation?)-```--### Layer 2: Biscuit (Authorization)-**Purpose:** Prove you can do specific things--```-"alice;allow_skill=risk-audit,weather-bot"--Lifetime: Unlimited (or revoked by removing from app)-Usage: Authorization (what can I do?)-```--### Layer 3: Message Signature (Proof of Ownership)-**Purpose:** Prove you sent a specific message--```-Agent Card:-{- "peer_id": "12D3Koo...",- "agent_card": {...},- "signature": "..." (signed with agent's Ed25519 key)-}--Lifetime: Single message-Usage: Proof (did this agent really send this?)-```--### Example Flow--```-1. Alice logs in- ββ Gets vouch (identity layer)--2. Alice publishes agent- ββ Signs Agent Card with Ed25519 key (proof layer)--3. Alice grants partner access- ββ Creates Biscuit token (authorization layer)--4. Partner calls Alice's agent- ββ Sends vouch (authentication: "I'm in the federation")- ββ Sends Biscuit token (authorization: "I can use risk-audit")- ββ Alice verifies both β executes-```-------## Multi-Federation Identity--An agent can have vouches from multiple federations:--```bash-# Alice logs into finance federation-sam identity login --hub https://identity-finance.acme.corp--# Alice logs into operations federation-sam identity login --hub https://identity-ops.acme.corp-```--Storage:--```-~/.config/sam/-βββ federations/-β βββ finance.db-β β βββ vouches: {alice β {subject: alice, issued_at: ...}}-β βββ operations.db-β βββ vouches: {alice β {subject: alice, issued_at: ...}}-```--**Key:** Each vouch is federation-scoped, stored in that federation's database.-------## The Hub: Simple Identity Server--The hub is **not** a gateway. It's a simple service that:--1. Verifies credentials (LDAP, OAuth, database, whatever)-2. Issues a signed vouch-3. Returns the vouch-4. Forgets the request (stateless)--### Hub Implementation (Pseudocode)--```go-type Hub struct {- privateKey ed25519.PrivateKey- credential_checker CredentialChecker // LDAP, database, etc-}--func (h *Hub) Login(username, password string, federation string) (*Vouch, error) {- // 1. Verify credentials- if !h.credential_checker.Verify(username, password) {- return nil, ErrInvalidCredentials- }-- // 2. Generate PeerID from username (deterministic)- peerID := DeterministicPeerID(username)-- // 3. Create vouch- vouch := &Vouch{- Subject: username,- PeerID: peerID,- Federation: federation,- IssuedAt: time.Now(),- ExpiresAt: time.Now().AddDate(1, 0, 0),- }-- // 4. Sign it- vouch.Signature = ed25519.Sign(h.privateKey, vouch.Bytes())-- // 5. Return (don't store)- return vouch, nil-}-```--**Key properties:**-- **Stateless**: No database of issued vouches-- **Offline-capable**: Once issued, vouch works without the hub-- **Deterministic PeerID**: Same username always yields same PeerID-------## Revocation: The Hard Problem--Traditional systems can revoke a credential instantly:--```-Hub: "User is revoked"-β All agents reject user immediately-```--SAM cannot do this (no central authority), so:--### SAM Revocation Strategy--1. **Short vouch lifetime** (e.g., 1 year)-2. **Biscuit-level revocation** (delete token from app)-3. **Hub-side certificate pinning** (hub can rotate keys)--**Scenario: Alice's credential is compromised**--1. Acme Corp revokes Alice in their hub-2. Alice's existing vouch is still valid (until expiry)-3. Alice cannot login again (hub rejects credentials)-4. New vouches cannot be issued to Alice-5. Existing vouches eventually expire--**Mitigation:**-- Use short vouch lifetime (e.g., 3 months instead of 1 year)-- Implement hub-side key rotation (revoke all vouches by retiring keys)-- Use Biscuit token revocation at application level-------## Hub Operator Trust Model--**SAM does NOT eliminate hub trust completely.** Here's why:--```-Issue: Who do you trust to verify credentials?--Option A: Acme Corp's hub (knows all of Acme's employees)-Option B: Certificate authority (verifies acme.corp domain)-Option C: Peer recommendation (other agents vouch for you)-```--**SAM supports all three:**--- **Option A** (Hub):- ```bash- sam-agent identity login --hub https://identity.acme.corp- ```--- **Option B** (Certificate pinning):- ```bash- sam-agent identity login --hub https://identity.acme.corp \- --pin-certificate /path/to/cert.pem- ```--- **Option C** (Peer vouching):- ```bash- sam vouch create alice \- --subject alice.smith \- --issued-by bob.jones- ```--**The design principle:**-> Move as much trust as possible from *authorities* to *cryptography*.-------## PeerID Derivation--Each agent has a **deterministic PeerID** derived from identity:--```go-// Traditional: Random PeerID-peerID := libp2p.NewRandomPeerID() // 12D3KooXABC...--// SAM: Deterministic from identity-publicKey := DerivePublicKey("[email protected]")-peerID := PeerIDFromPublicKey(publicKey) // Always 12D3KooXABC...-```--**Benefits:**--1. **Reproducible**: Same identity always yields same PeerID-2. **Auditable**: Can verify identity from PeerID-3. **Lightweight**: No key management service needed--**How it works:**--```-Identity: "[email protected]"- β-SHA256 hash: "abc123..."- β-Ed25519 key derivation: "abc123..." β PublicKey- β-PeerID: libp2p.IDFromPublicKey(publicKey)- β-Result: "12D3KooXA7cBj4VKrpv7HzKLmvnWKLVqZZHJm9NyN6Td3Y4hMWjK"-```-------## Offline Workflow--After authentication, agents can work completely offline:--```bash-# Online: Alice logs in-sam identity login --hub https://identity.acme.corp--# Offline: Publish agent-sam publish --skill risk-audit --mcp-port 8080--# Offline: Call another agent (if both are in same LAN)-sam call bob.jones --message "hello"--# Offline: Inspect credential-sam inspect biscuit "bob;allow_skill=risk-audit"-```--**No internet required** for any of these operations (after initial login).-------## Summary: Identity Without Central Authority--| Aspect | Traditional | SAM |-|--------|-------------|-----|-| **Where identity is verified** | Central server (every time) | Local vouch (once) |-| **How trust is established** | Server state | Cryptographic signature |-| **Offline support** | No | Yes (after login) |-| **Revocation speed** | Instant | By vouch expiry |-| **Trust dependencies** | IdP must exist | Hub must exist at login time |-| **Federation support** | Single IdP | Multiple hubs per agent |-------## Next Steps--- **[Biscuit Authorization](#/concepts/biscuit.md)**: How skill-based access control works-- **[Federation & Storage](#/concepts/federation.md)**: How federation isolation works-- **[A2A Protocol](#/concepts/a2a-protocol.md)**: How agents authenticate to each otherdiff --git a/docs/contributing.md b/docs/contributing.mddeleted file mode 100644index b805cd54..00000000--- a/docs/contributing.md+++ /dev/null@@ -1,529 +0,0 @@-# Contributing to SAM--We welcome contributions! This guide covers:--1. **Development Setup**: Get SAM building locally-2. **Code Style**: Follow SAM conventions-3. **Testing**: Ensure quality with full test coverage-4. **Submitting Changes**: PR workflow-------## Development Setup--### Prerequisites--- **Go 1.21+**: https://golang.org/doc/install-- **Make**: `sudo apt-get install make` (Linux) or `brew install make` (macOS)-- **BATS**: `sudo apt-get install bats` (Linux) or `brew install bats-core` (macOS)-- **Git**: For version control--### Clone and Build--```bash-# Clone the repository-git clone https://github.com/aojea/sam.git-cd sam--# Build the binary-make build--# Verify build-./bin/sam --help-```--### Environment Setup--```bash-# Set GOPATH (if not already set)-export GOPATH=$HOME/go--# Add to PATH-export PATH=$PATH:$GOPATH/bin--# Run tests-make test-```-------## Code Style--### Go Conventions--SAM follows standard Go conventions:--1. **Formatting**: Use `gofmt`- ```bash- gofmt -s -w cmd/sam/main.go- ```--2. **Linting**: Use `golangci-lint`- ```bash- go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest- golangci-lint run ./...- ```--3. **Naming**- - Package names: lowercase, no underscores (`samnet`, not `sam_net`)- - Function names: `CamelCase` (exported) or `camelCase` (private)- - Constants: `UPPER_CASE` (exported) or `upper_case` (private)- - Interfaces: `Reader`, `Writer`, `Closer` (noun + verb pattern)--4. **Comments**- ```go- // Package net provides libp2p networking for SAM agents.- package net-- // Node represents a libp2p host with DHT routing.- type Node interface {- // Start begins listening and DHT discovery.- Start(ctx context.Context) error- }- ```--5. **Error Handling**- ```go- // Good- if err != nil {- return fmt.Errorf("loading vouch: %w", err)- }-- // Bad- if err != nil {- panic(err) // Don't panic in libraries- }- ```--### File Organization--```-sam/-βββ cmd/sam/ # CLI commands-β βββ main.go # Entry point-β βββ root.go # Root command-β βββ publish.go # Publish command-β βββ call.go # Call command-β βββ ...-βββ pkg/ # Libraries (exported)-β βββ net/ # Networking-β β βββ node.go-β β βββ options.go-β β βββ node_test.go-β βββ protocol/ # Protocols-β β βββ a2a.go-β β βββ agent_card.go-β β βββ a2a_test.go-β βββ economy/ # Credentials and payments-β β βββ biscuit.go-β β βββ middleware.go-β β βββ biscuit_test.go-β βββ identity/ # Identity and authentication-β βββ vouch.go-β βββ device_flow.go-β βββ vouch_test.go-βββ internal/ # Internal packages (not exported)-β βββ db/ # Database abstractions-β β βββ manager.go-β β βββ store.go-β β βββ codec.go-β βββ testutils/ # Testing helpers-β βββ userns.go-βββ tests/ # Test suites-β βββ integration/ # Go integration tests-β β βββ a2a_test.go-β β βββ cuj_test.go-β β βββ mesh_test.go-β βββ e2e/ # BATS E2E tests-β βββ sam.bats-βββ docs/ # Documentation- βββ README.md- βββ guides/- βββ cli/- βββ concepts/-```-------## Testing--### Test Coverage Requirements--All contributions must include tests:--1. **Unit tests** for new functions-2. **Integration tests** for multi-node scenarios-3. **E2E tests** for CLI changes--### Running Tests--```bash-# All tests-make test--# Unit + Integration only-go test -race -count=1 ./...--# E2E only-make build-make test-e2e--# Specific test-go test -run TestFunctionName ./pkg/package--# With coverage-go test -cover ./...-```--### Writing Unit Tests--```go-func TestNewBiscuit(t *testing.T) {- // Arrange- parser := economy.SimpleBiscuitParser{}- token := "alice;allow_skill=weather"-- // Act- parsed, err := parser.Parse(context.Background(), token)-- // Assert- if err != nil {- t.Fatalf("Parse failed: %v", err)- }- if parsed.Subject != "alice" {- t.Errorf("Expected 'alice', got %q", parsed.Subject)- }-}-```--### Writing Integration Tests--```go-func TestA2ACallWithBiscuit(t *testing.T) {- testutils.Run(t, func(f *testutils.Framework) {- // Setup- nodea, _ := f.StartNode("federation-a")- nodeb, _ := f.StartNode("federation-a")-- // Execute- token := "alice;allow_skill=test-skill"- resp, err := protocol.Execute(- context.Background(),- nodea.Host(),- protocol.ExecuteRequest{- Target: nodeb.PeerID(),- Capability: "test-skill",- Biscuit: token,- MCPRequest: []byte(`{"method": "test"}`),- },- )-- // Assert- if err != nil {- t.Fatalf("Execute failed: %v", err)- }- if resp == nil {- t.Errorf("Expected response")- }- }, testutils.CLONE_NEWNET)-}-```--### Writing BATS Tests--```bash-@test "sam publish with dry-run outputs card" {- run "$SAM_BINARY" publish \- --skill test-skill \- --mcp-port 9999 \- --dry-run=client-- [[ "$status" -eq 0 ]]- [[ "$output" == *'"peer_id"'* ]]- [[ "$output" == *'test-skill'* ]]-}-```--### Race Detection--Always test with race detection:--```bash-go test -race ./...-```--This catches data races that are hard to spot manually.-------## Submitting Changes--### 1. Create a Branch--```bash-git checkout -b feature/my-feature-# or-git checkout -b fix/issue-123-```--### 2. Make Changes--```bash-# Edit files-vim pkg/net/node.go--# Run tests frequently-go test -race ./pkg/net-```--### 3. Commit with Good Messages--```bash-git add -A-git commit -m "Add federation isolation to DHT discovery--- Scopes DHT announcements to /sam/fed/<id> namespace-- Prevents cross-federation peer discovery-- Matches federation DHT protocol prefix--Fixes #123"-```--**Commit message format:**-```-<type>: <description>--<body explaining why>--Fixes #<issue-number>-```--**Types:** `feat`, `fix`, `refactor`, `test`, `docs`, `chore`--### 4. Keep Branch Up to Date--```bash-git fetch origin-git rebase origin/main-```--### 5. Push and Create PR--```bash-git push origin feature/my-feature-```--Then create a PR on GitHub with:-- **Title**: Brief summary-- **Description**: What changed and why-- **Tests**: Mention test coverage-- **Fixes**: Reference any related issues (#123)--### 6. Code Review--- Address reviewer feedback-- Push additional commits (don't force-push)-- Reviewer will merge when approved-------## Common Development Tasks--### Adding a New CLI Command--1. **Create command file** (`cmd/sam/mycommand.go`):- ```go- func newMyCmd(cfg *runConfig) *cobra.Command {- cmd := &cobra.Command{- Use: "mycommand",- Short: "Do something",- RunE: func(cmd *cobra.Command, args []string) error {- return runMyCommand(cmd.Context(), cfg)- },- }- // Add flags- cmd.Flags().StringVar(&cfg.flag, "flag", "", "description")- return cmd- }-- func runMyCommand(ctx context.Context, cfg *runConfig) error {- // Implementation- return nil- }- ```--2. **Register in root** (`cmd/sam/root.go`):- ```go- cmd.AddCommand(newMyCmd(cfg))- ```--3. **Add tests** (`tests/e2e/sam.bats`):- ```bash- @test "sam mycommand --help works" {- run "$SAM_BINARY" mycommand --help- [[ "$status" -eq 0 ]]- }- ```--### Adding a New Protocol Feature--1. **Define interface** (`pkg/protocol/myfeature.go`):- ```go- type MyFeature interface {- DoSomething(ctx context.Context) error- }- ```--2. **Implement** (`pkg/protocol/myfeature.go`):- ```go- type myFeatureImpl struct {- // fields- }-- func (m *myFeatureImpl) DoSomething(ctx context.Context) error {- // implementation- }- ```--3. **Add tests** (`pkg/protocol/myfeature_test.go`):- ```go- func TestMyFeature(t *testing.T) {- // test implementation- }- ```--### Debugging Issues--```bash-# Verbose logging-SAM_DEBUG=1 go test -v ./...--# GDB debugging-dlv test ./pkg/net--# CPU profiling-go test -cpuprofile=cpu.prof ./...-go tool pprof cpu.prof--# Memory profiling-go test -memprofile=mem.prof ./...-go tool pprof mem.prof-```-------## Code Review Checklist--Before submitting a PR, ensure:--- [ ] Code follows Go style guidelines-- [ ] All tests pass: `go test -race ./...`-- [ ] New code has tests-- [ ] Integration tests pass: `go test -race -count=1 ./tests/integration`-- [ ] E2E tests pass: `make test-e2e`-- [ ] Comments explain non-obvious logic-- [ ] Error messages are descriptive-- [ ] No panics in libraries (use errors)-- [ ] No TODO/FIXME comments (create issues instead)-- [ ] Documentation is updated-------## Reporting Issues--When reporting bugs, include:--1. **Expected behavior**: What should happen?-2. **Actual behavior**: What happens instead?-3. **Steps to reproduce**: How to trigger the bug?-4. **Environment**: Go version, OS, architecture-5. **Logs**: Error messages and stack traces--### Example Issue--```-Title: sam call fails with "unknown peer" when federation is not set--Expected: sam call should use default federation-Actual: sam call fails with "unknown peer"--Steps:-1. sam publish --skill test --mcp-port 8080-2. sam call test --message "hello"--Environment:-- Go 1.21-- Ubuntu 22.04-- SAM commit abc123--Error:- Error: discovering capability "test": no peers found for capability "test"-```-------## Design Discussion--For significant changes, please open an issue first to discuss:--- **Architecture changes**: How will this affect the system?-- **Protocol changes**: Will this affect peer compatibility?-- **Breaking changes**: How should we handle migration?-------## Documentation--All features should have corresponding documentation:--1. **API docs**: Godoc comments on exported types/functions-2. **User guides**: CLI examples in `/docs/guides/`-3. **Concepts**: Technical explanations in `/docs/concepts/`-4. **CLI reference**: Command documentation in `/docs/cli/`--### Godoc Example--```go-// Node represents a libp2p host with DHT routing.-// It manages connectivity, peer discovery, and protocol handlers.-type Node interface {- // Start begins the node listening and starts DHT discovery.- // Returns error if the node is already started.- Start(ctx context.Context) error-- // Stop gracefully shuts down the node.- // All streams and protocols are closed.- Stop(ctx context.Context) error-- // Host returns the underlying libp2p host.- Host() host.Host-- // PeerID returns the unique identifier for this node.- PeerID() peer.ID-}-```-------## Community--- **Issues**: Report bugs and request features-- **Discussions**: Ask questions and share ideas-- **Pull Requests**: Contribute code-- **Slack/Discord**: (if applicable)-------## License--All contributions are licensed under the same license as SAM (typically MIT or Apache 2.0). By contributing, you agree to this.-------## Questions?--- **Open an issue** for bug reports or features-- **Start a discussion** for design questions-- **Check the docs**: https://docs.sam.dev--Thank you for contributing! πdiff --git a/docs/faq.md b/docs/faq.mddeleted file mode 100644index 04584bb1..00000000--- a/docs/faq.md+++ /dev/null@@ -1,186 +0,0 @@-# FAQ: Frequently Asked Questions--## What is SAM?--SAM (Sovereign Agent Mesh) is a zero-trust networking layer for autonomous agents.-It provides peer discovery, identity verification, and capability authorization over pure libp2p.--## Getting Started--### How do I install SAM?--```bash-git clone https://github.com/aojea/sam.git-cd sam-make build-./bin/sam-agent --help-```--Requirements: Go 1.21+, Make, BATS (for E2E tests).--### How do I publish my first agent?--1. Authenticate with your hub:--```bash-sam-agent identity login --hub <your-hub-url>-```--2. Publish a local MCP capability:--```bash-sam-agent publish --skill mycapability --mcp-port 8080-```--### How do I call an agent?--```bash-sam-agent call mycapability --message "Do something"-```--## Core Concepts--### Do I need to manage federations manually?--No. SAM now runs with a single default federation namespace at runtime.-The old federation management CLI commands were removed.--### What is a passport biscuit?--A passport biscuit is the identity credential issued by the hub and bound to your peer identity.-It is used for authentication during peer establishment.--### What is a Biscuit token?--A Biscuit token grants capability-level authorization.-Example format:--`alice;allow_skill=weather-bot,risk-audit`--### What is an agent card?--A signed manifest published to the DHT containing peer id, skills, and resources.--## Architecture and Security--### Why peer-to-peer instead of a gateway?--P2P avoids centralized bottlenecks and trust chokepoints.-Peers communicate directly, and trust is cryptographic.--### Is SAM production-ready?--SAM is in active development. Core paths are tested, but you should apply standard production hardening:-- secure key storage-- short credential lifetimes-- monitoring and incident response--### How do I protect credentials?--- keep local config directory protected by OS permissions-- rotate hub credentials regularly-- inspect biscuits before sharing--## Networking--### Can SAM work behind NAT?--Yes. SAM relies on libp2p connectivity features including relay and hole punching.--### Can I run a node in the cloud?--Yes.--```bash-sam-agent up --listen /ip4/0.0.0.0/udp/4001/quic-v1-```--## Performance--### How many peers can it handle?--The practical limit depends on network and host resources.-For most deployments, discovery latency is dominated by DHT topology and cache warmth.--### How fast are calls?--Call latency is usually the sum of:-- discovery time (first lookup can be slower)-- connection establishment-- remote tool execution time--## Operations--### Where are credentials and state stored?--```text-~/.config/sam/-βββ identity/-β βββ credentials.json-βββ federations/- βββ default.db-```--### How do I back up local state?--```bash-cp ~/.config/sam/federations/default.db ~/backup/default.db.backup-cp -r ~/.config/sam/identity ~/backup/identity.backup-```--### How do I refresh identity credentials?--```bash-sam-agent identity login --hub <hub-url>-```--### How do I debug a failed call?--1. Confirm identity is present:--```bash-sam-agent identity whoami-```--2. Check visible agents:--```bash-sam-agent mesh get agents-```--3. Dry-run request:--```bash-sam-agent call mycapability --message "test" --dry-run=client-```--4. Increase logging:--```bash-SAM_DEBUG=1 sam-agent call mycapability --message "test"-```--## Integration--### Can I use SAM as a library?--Yes. Import SAM packages in Go and construct a node with `sam/pkg/net`.--### Can I run SAM in Docker/Kubernetes?--Yes. Persist `~/.config/sam` and expose libp2p ports as needed.--## Development--### How do I run tests?--```bash-go test -race ./...-make build-make test-e2e-```--### Where do I report bugs?--Open an issue at:-https://github.com/aojea/sam/issuesdiff --git a/docs/glossary.md b/docs/glossary.mddeleted file mode 100644index 13e772d9..00000000--- a/docs/glossary.md+++ /dev/null@@ -1,277 +0,0 @@-# Glossary--## A--**A2A**: Agent-to-Agent. RPC protocol for agents to call each other over libp2p streams.--**Agent**: An autonomous program that can publish skills to a federation and call skills offered by other agents.--**Agent Card**: Signed manifest published by an agent to the DHT, containing skills, resources, and signature.--**Authorization**: Determining what an authenticated agent is allowed to do (e.g., which skills it can invoke).--## B--**Biscuit**: Lightweight credential with caveats granting access to specific skills. Format: `subject;allow_skill=X,Y,Z`--**Blockade**: (Future) Mechanism to revoke agent identity in a federation.--**Bolt/bbolt**: Embedded key-value database used for federation storage. Pure Go, no external dependencies.--**Bootstrap**: Peer addresses used to join the DHT. Agents connect to bootstrap nodes to discover peers.--**Bytecode**: (Not used in SAM) Biscuit tokens are plain-text, not bytecode.--## C--**Capability**: Synonym for skill. The set of things an agent can do.--**Caveat**: Restriction in a Biscuit token (e.g., `allow_skill=X`).--**Certificate**: Cryptographic proof of identity, typically Ed25519 key.--**Cipher**: Encryption algorithm used in TLS transport (not user-facing in SAM).--**CLONE_NEWNET**: Linux namespace for network isolation in integration tests.--**Codec**: Encoder/decoder for serialization (JSON, bincode, etc.).--**Consensus**: SAM does NOT use consensus. Each federation manages independently.--**Cryptography**: Mathematical science for secure communication. SAM uses Ed25519 for signing and libp2p for TLS.--## D--**Dark Mesh**: Enterprise network where agents operate in isolation, not visible to the public mesh. Uses federation isolation.--**DCUtR**: Direct Connection UpgRade. libp2p mechanism for hole-punching through NAT.--**Delegation**: (Future) Allowing an agent to grant a subset of its skills to another agent.--**Device Flow**: OAuth-like authentication where a device opens a browser to authenticate (used by `sam identity login`).--**DHT**: Distributed Hash Table. Peer discovery mechanism used by libp2p. SAM scopes DHT announcements to federation namespaces.--**Dry-run**: Preview mode for commands. `--dry-run=client` builds locally, `--dry-run=server` skips final commit.--## E--**Ed25519**: Public-key cryptography algorithm for signing. Standard in libp2p.--**Economy**: Package in SAM for credentials, payments, and authorization.--**Endpoint**: URL where an MCP resource is available (e.g., `http://127.0.0.1:8080`).--**Enrollment**: Process of joining a federation (login + credential storage).--## F--**Federation**: Isolated P2P network where agents discover and call each other. Each federation has own DHT namespace and storage.--**Federation Gate**: Component that checks if a caller is in the federation (vouch verification).--**Federation ID**: Deterministic identifier for a federation, derived from name.--**Firewall**: Network filter. SAM uses libp2p's QUIC and WebSocket to traverse firewalls.--## G--**Gateway**: Central server that intermediates peer connections. SAM avoids gateways by using direct P2P.--**Governance**: Rules for a federation (who can join, which skills are allowed, etc.). SAM delegates to federation operators.--**gRPC**: RPC framework (not used in SAM; SAM uses libp2p streams + MCP).--## H--**Hub**: Identity server that issues vouches. Contacted once per login, then vouch is cached locally.--**Hole-Punch**: Technique for NAT traversal using ICE. libp2p DCUtR implements this.--**HSM**: Hardware Security Module for secure key storage.--## I--**Identity**: Proof of who you are. In SAM: cryptographic (Ed25519 key) + vouch.--**Identity Provider (IdP)**: Server that verifies credentials and issues tokens. SAM integrates with existing IdPs via hub.--**Isolation**: Separation of network namespaces to prevent cross-federation discovery.--## J--**JSON**: Serialization format used for Agent Cards, calls, and CLI output.--## K--**Key**: Cryptographic secret (Ed25519 private key). Stored in `~/.config/sam/identity/keystore.json`.--**Keyring**: Encrypted credential storage on OS (macOS Keychain, Linux Secret Service, Windows Credential Manager).--## L--**libp2p**: Modular P2P networking library used for connectivity, DHT, and relays. The foundation of SAM.--**Linux Namespace**: OS-level isolation for network, filesystem, etc. Used in integration tests.--**Listen Address**: Multiaddr where a node listens for connections (e.g., `/ip4/0.0.0.0/tcp/4001`).--## M--**Mesh**: Network of interconnected agents. SAM enables zero-trust meshes.--**MCP**: Model Context Protocol. Protocol for agents to define resources and capabilities.--**Middleware**: Component that processes requests/responses (e.g., `BiscuitSkillGate`).--**Micropayment**: Small payment sent with A2A call. Currently placeholder, future feature.--**Multiaddr**: Multi-protocol address format used by libp2p (e.g., `/ip4/127.0.0.1/tcp/8080`).--## N--**NAT**: Network Address Translation. Makes direct connections difficult. libp2p uses relays and hole-punching to overcome.--**Namespace**: DHT protocol prefix for scoping discovery (e.g., `/sam/fed/finance`).--**Nonce**: Number used once, for security. Used in micropayments to prevent replay.--## O--**OAuth/OIDC**: Standard authentication protocols. SAM doesn't use these; instead uses vouches.--**Offline**: Mode where SAM operates without network connectivity (possible with cached vouches).--**Operator**: Person or organization running a federation hub or node.--## P--**Peer**: Node in the P2P network identified by PeerID.--**PeerID**: Unique identifier for a libp2p node, derived from its Ed25519 public key.--**Peering**: Process of connecting two nodes directly.--**Permission**: Synonym for capability/skill.--**Private Key**: Secret cryptographic key used for signing. Never shared.--**Protocol**: Set of rules for communication. SAM defines `/sam/a2a/1.0` for agent calls.--**Proxy**: Intermediary that relays traffic. SAM avoids proxies where possible, uses libp2p relays as fallback.--**Public Key**: Cryptographic key that anyone can see. Used to verify signatures.--## Q--**QUIC**: UDP-based protocol often more lenient through firewalls than TCP.--## R--**Reputation**: System for tracking agent trustworthiness (future feature).--**Revocation**: Disabling a credential (vouch or Biscuit). SAM revokes by expiry or manual deletion.--**Relay**: Node that forwards traffic between peers that cannot connect directly.--## S--**SAM**: Sovereign Agent Mesh. Zero-trust P2P networking for agents.--**Schema**: Structure definition (e.g., Agent Card schema, vouch schema).--**Secret**: Sensitive data (private keys, credentials). Always protected.--**Signature**: Cryptographic proof that something was signed by a key. Ed25519 signatures in SAM.--**Skill**: Capability offered by an agent (e.g., "weather-bot", "risk-audit").--**Sovereign**: Having control over one's own identity and operations (not delegated to a central authority).--**Stream**: Bidirectional connection over libp2p for A2A communication.--**Subject**: Entity that holds a credential (username, email, etc.).--## T--**Token**: Credential granted to an agent. In SAM: vouch (identity) or Biscuit (authorization).--**TLS**: Transport Layer Security. Encryption used by libp2p for all connections.--**Timeout**: Maximum time to wait for an operation.--**Trust Desert**: Problem where agents operate without trust, in systems with central gatekeepers.--**Trustworthy**: An agent with good reputation (future feature).--## U--**UID**: User ID, usually a number (not used in SAM; uses usernames/emails).--**UUID**: Universally Unique Identifier. SAM derives deterministic IDs from usernames.--**Unencrypted**: Not encrypted. SAM never sends unencrypted credentials (uses TLS).--## V--**Voucher**: Component that manages vouch lifecycle.--**Vouch**: Cryptographic credential proving membership in a federation. Issued by hub, cached locally.--**Verify**: Cryptographic check that something is valid (signature, expiry, etc.).--## W--**Whitelist**: List of allowed peers or skills. SAM uses Biscuit caveats for skill whitelists.--**WebSocket**: Protocol for connections over HTTP. Used by libp2p for firewall traversal.--## X--**X.509**: Standard for digital certificates (not used in SAM; uses Ed25519 keys).--## Y--**YAML**: Configuration format (not used in SAM; uses CLI flags and JSON).--## Z--**Zero-Trust**: Security model where no entity is trusted by default. Everything must prove legitimacy. SAM's core philosophy.-------## Acronyms Quick Reference--| Acronym | Full Name |-|---------|-----------|-| A2A | Agent-to-Agent |-| BATS | Bash Automated Testing System |-| DCUtR | Direct Connection UpgRade |-| DHT | Distributed Hash Table |-| Ed25519 | Elliptic Curve Signature Scheme |-| GOPATH | Go Package Path |-| gRPC | Google Remote Procedure Call |-| HSM | Hardware Security Module |-| ICE | Interactive Connectivity Establishment |-| IdP | Identity Provider |-| JSON | JavaScript Object Notation |-| KMS | Key Management Service |-| LDAP | Lightweight Directory Access Protocol |-| MCP | Model Context Protocol |-| NAT | Network Address Translation |-| OIDC | OpenID Connect |-| P2P | Peer-to-Peer |-| PeerID | Peer Identifier |-| QUIC | Quick UDP Internet Connection |-| RPC | Remote Procedure Call |-| SAM | Sovereign Agent Mesh |-| TLS | Transport Layer Security |-| UUID | Universally Unique Identifier |-------## See Also--- **[Concepts](#/concepts/federation.md)**: Technical deep dives-- **[FAQ](#/faq.md)**: Common questions answered-- **[CLI Reference](#/cli/reference.md)**: Command documentationdiff --git a/docs/guides/dark-mesh.md b/docs/guides/dark-mesh.mddeleted file mode 100644index 54bf1814..00000000--- a/docs/guides/dark-mesh.md+++ /dev/null@@ -1,101 +0,0 @@-# Dark Mesh: End-to-End Walkthrough--This guide shows a full SAM flow using passport-based authentication and Biscuit capability authorization.--## Scenario--- Team A publishes a private capability (`risk-audit`).-- Team B discovers and calls it.-- All traffic remains peer-to-peer.--## Step 1: Start a Node--```bash-sam-agent up --dht-mode server-```--Keep this running in one terminal.--## Step 2: Authenticate Identity--In another terminal:--```bash-sam-agent identity login --hub https://identity.example.com-sam-agent identity whoami-```--This stores local credentials and a passport biscuit.--## Step 3: Publish a Capability--Assuming your MCP server is on `:8080`:--```bash-sam-agent publish --skill risk-audit --mcp-port 8080-```--Optional safety preview:--```bash-sam-agent publish --skill risk-audit --mcp-port 8080 --dry-run=client-```--## Step 4: Discover Agents--```bash-sam-agent mesh get agents-sam-agent mesh get agents --capability risk-audit -o json-```--## Step 5: Call the Capability--```bash-sam-agent call risk-audit --message "audit this report"-```--Optional request validation:--```bash-sam-agent call risk-audit --message "audit this report" --dry-run=client-```--## Step 6: Audit Artifacts--```bash-sam-agent inspect biscuit "partner-bot;allow_skill=risk-audit"-sam-agent inspect card '{"peer_id":"...","agent_card":{...}}'-```--## Troubleshooting--1. No peers found:--```bash-sam-agent mesh get agents --watch-```--2. Unauthorized errors:--```bash-sam-agent identity whoami-sam-agent identity login --hub https://identity.example.com-```--3. Connectivity issues:--```bash-sam-agent up --relay-service --run-for 30s-```--4. Detailed logs:--```bash-SAM_DEBUG=1 sam-agent call risk-audit --message "test"-```--## Security Notes--- Identity authentication is passport-based at peer establishment time.-- Authorization remains capability-scoped via Biscuit caveats.-- Runtime uses a fixed default mesh namespace.diff --git a/docs/guides/hub-key-management.md b/docs/guides/hub-key-management.mddeleted file mode 100644index eb5e55e2..00000000--- a/docs/guides/hub-key-management.md+++ /dev/null@@ -1,251 +0,0 @@-# Hub Key Management--The SAM hub manages two types of Ed25519 keys:--1. **Signing Key**: Used to digitally sign identity biscuits (passports)-2. **Identity/TLS Key**: Used for the hub's libp2p peer identity and TLS handshakes (when running with `--enable-p2p`)--## Key Generation--Generate both keys:--```bash-sam-hub keygen --with-identity-```--Output example:--```-=== Passport Signing Key (Ed25519) ===-Purpose: Sign identity biscuits-Environment: SAM_HUB_KEY--Private Key (base64):-4XkwpAJ0C9vqXkL...--Public Key (base64, published at /.well-known/sam-hub-keys):-GvK2pxM9d3sY8zL...--=== Hub Peer Identity Key (Ed25519 for libp2p TLS) ===-Purpose: Hub's libp2p peer identity and TLS handshakes-Environment: SAM_HUB_IDENTITY_KEY--Private Key (base64):-AwV3dY7pQ4sL2xN...--Public Key (base64):-B1Z5cX8mR6wL3yO...--Hub Peer ID: Use 'sam-hub serve --enable-p2p' to print the peer ID-Configure as bootstrap: --bootstrap /ip4/HUB_IP/udp/PORT/quic-v1/p2p/PEER_ID-```--## Configuration--### HTTP-Only Mode (No libp2p)--Suitable for cloud deployments behind a load balancer:--```bash-# Development (uses deterministic seed)-sam-hub serve --http-listen :8081--# Production (with custom signing key)-export SAM_HUB_KEY="4XkwpAJ0C9vqXkL..."-sam-hub serve --http-listen 0.0.0.0:8081-```--### P2P Rendezvous Mode--Enable the hub as a DHT bootstrap/rendezvous point:--```bash-# Development (generates ephemeral peer identity)-sam-hub serve --enable-p2p--# Production (with configured keys)-export SAM_HUB_KEY="4XkwpAJ0C9vqXkL..."-export SAM_HUB_IDENTITY_KEY="AwV3dY7pQ4sL2xN..."-sam-hub serve \- --http-listen 0.0.0.0:8081 \- --p2p-listen /ip4/0.0.0.0/udp/9000/quic-v1,/ip4/0.0.0.0/tcp/9001 \- --enable-p2p-```--After startup, the hub prints its peer ID and multiaddrs:--```-=== libp2p Host ===-Peer ID: 12D3KooWJqYwgPjYqC6Y3...--Multiaddrs:- /ip4/10.0.0.5/udp/9000/quic-v1/p2p/12D3KooWJqYwgPjYqC6Y3...- /ip4/10.0.0.5/tcp/9001/p2p/12D3KooWJqYwgPjYqC6Y3...-```--Share these with agents as bootstrap peers.--## Key Rotation--### Signing Key Rotation--When rotating the signing key:--1. Generate a new key: `sam-hub keygen`-2. Update `SAM_HUB_KEY` in your deployment-3. Restart the hub gracefully-4. Agents automatically fetch the new public key from `/.well-known/sam-hub-keys`--Existing passports remain valid (keep the old key for verification if needed).--### Identity Key Rotation--When rotating the libp2p identity key:--1. Generate a new key: `sam-hub keygen --with-identity`-2. Update `SAM_HUB_IDENTITY_KEY` in your deployment-3. Restart the hub-4. Update agent bootstrap peer configuration with the new peer ID and multiaddrs--This changes the hub's peer ID, so agents must reconfigure.--## Security Practices--### Key Storage--- **Use secrets management**: Kubernetes Secrets, AWS Secrets Manager, HashiCorp Vault, etc.-- **Encrypt at rest**: Ensure key material is encrypted when stored-- **Restrict access**: Only the hub process should have access to private keys-- **Audit logging**: Log all key operations and passport issuance--Example Kubernetes Secret:--```yaml-apiVersion: v1-kind: Secret-metadata:- name: sam-hub-keys-type: Opaque-stringData:- SAM_HUB_KEY: |- 4XkwpAJ0C9vqXkL...- SAM_HUB_IDENTITY_KEY: |- AwV3dY7pQ4sL2xN...-```--### Key Rotation Schedule--- **Signing key**: Rotate annually or after suspected compromise-- **Identity key**: Rotate on topology changes or annually-- **Emergency rotation**: If a key is suspected compromised, rotate immediately--### TLS Specifics--libp2p uses **certificate-based TLS** with Ed25519 keys:-- The private key signs the TLS certificate-- Certificates are self-signed and ephemeral-- The public key is derived from the private key-- No external CA or X.509 infrastructure needed--For **FIPS compliance**, ensure Go is compiled with `GOEXPERIMENT=boringcrypto` and libp2p's TLS security transport is the only configured security transport.--## Client-Side Verification--Agents verify biscuit signatures using the hub's public signing key. The key is published at:--```bash-curl https://hub.example.com/.well-known/sam-hub-keys-```--Response:--```json-{- "issuer": "app.sam-mesh.dev",- "keys": [- {- "kid": "sam-hub-root-v1",- "alg": "Ed25519",- "k": "GvK2pxM9d3sY8zL..."- }- ]-}-```--Clients cache this public key for offline verification without requiring network calls.--## Troubleshooting--### Invalid Key Format--Error: `decoding SAM_HUB_KEY: illegal base64 data at input byte`--- Ensure keys are base64url-encoded (no padding)-- Use `sam-hub keygen` to generate properly formatted keys--### Peer ID Mismatch--Error: `passport peer mismatch` or `passport authentication failed`--- Verify the hub is using the correct signing key-- Ensure all hub instances (if load-balanced) use the same signing key-- Check agents are fetching the correct public key from `/.well-known/sam-hub-keys`--### Bootstrap Connection Failed--Error: `connecting to hub bootstrap peer: ...`--- Verify the peer ID and multiaddrs are correct-- Check hub is reachable at the advertised address-- Ensure TLS/QUIC connections are not blocked by firewalls--## Integration with Kubernetes--```yaml-apiVersion: v1-kind: Secret-metadata:- name: sam-hub-keys-type: Opaque-stringData:- SAM_HUB_KEY: 4XkwpAJ0C9vqXkL...- SAM_HUB_IDENTITY_KEY: AwV3dY7pQ4sL2xN...-------apiVersion: apps/v1-kind: Deployment-metadata:- name: sam-hub-spec:- replicas: 1- template:- spec:- containers:- - name: hub- image: sam-hub:latest- args:- - serve- - --http-listen=0.0.0.0:8081- - --p2p-listen=/ip4/0.0.0.0/udp/9000/quic-v1,/ip4/0.0.0.0/tcp/9001- - --enable-p2p- env:- - name: SAM_HUB_KEY- valueFrom:- secretKeyRef:- name: sam-hub-keys- key: SAM_HUB_KEY- - name: SAM_HUB_IDENTITY_KEY- valueFrom:- secretKeyRef:- name: sam-hub-keys- key: SAM_HUB_IDENTITY_KEY- ports:- - containerPort: 8081- name: http- - containerPort: 9000- protocol: UDP- name: p2p-quic- - containerPort: 9001- name: p2p-tcp-```diff --git a/docs/guides/hub-rendezvous.md b/docs/guides/hub-rendezvous.mddeleted file mode 100644index 9957c18a..00000000--- a/docs/guides/hub-rendezvous.md+++ /dev/null@@ -1,61 +0,0 @@-# Hub as Rendezvous Point--SAM uses the configured hub's hostname as the discovery namespace scope for peer capability advertisements. This enables:--1. **Capability Namespace Scoping**: All peer capability announcements are registered under `<hub-hostname>/<capability>` in the DHT.-2. **Centralized Discovery Index**: When agents discover peers by capability, they query the DHT for records under the hub's namespace.-3. **Bootstrap Topology**: To make the hub act as an active rendezvous point, configure it as a bootstrap peer so all agents connect to it during startup.--## Configuration--### CLI Usage--Set the hub and optionally bootstrap peers:--```bash-sam-agent up \- --hub https://identity.example.com \- --bootstrap /ip4/<hub-ip>/udp/0/quic-v1/p2p/<hub-peer-id> \- ...-```--When `--hub` is provided without an explicit bootstrap address, the CLI uses the hub's hostname as the rendezvous namespace default.--### Programmatic Usage--```go-import samnet "sam/pkg/net"--// Hub hostname becomes the rendezvous namespace-node, err := samnet.New(- samnet.WithRendezvousNamespace("identity.example.com"),- samnet.WithBootstrapPeers(/* hub peer multiaddr */),- // ...-)-```--## Hub Architecture--The hub (sam-hub) currently provides:-- HTTP endpoint for passport issuance (`:8081/issue-passport`)-- Health and metadata endpoints-- Future: optional libp2p host for direct rendezvous protocol support--To upgrade the hub to a full rendezvous server:-1. Add a libp2p host to sam-hub/main.go-2. Export the hub's peer ID and addresses for agent bootstrap configuration-3. Implement rendezvous protocol handlers for registration/discovery--## Discovery Flow--```-Agent A:- 1. Connect to hub (bootstrap peer)- 2. Announce capability: /sam/fed/default/<hub-hostname>/my-skill--Agent B:- 1. Connect to hub (bootstrap peer)- 2. Discover capability: /sam/fed/default/<hub-hostname>/my-skill- 3. Find Agent A in DHT results- 4. Connect and authenticate via /sam/auth/1.0.0-```diff --git a/docs/guides/hybrid-intelligence.md b/docs/guides/hybrid-intelligence.mddeleted file mode 100644index 54e209a7..00000000--- a/docs/guides/hybrid-intelligence.md+++ /dev/null@@ -1,172 +0,0 @@-# Hybrid Intelligence Audit--## Problem--You have sensitive local data (contracts, internal code, regulated documents) that cannot be uploaded to cloud LLMs, but you still need high-quality reasoning against public and constantly changing sources.--The target workflow is:--1. Read and sanitize private documents locally.-2. Pull current public policy/specification data from the web.-3. Synthesize one final audit report.--## Architecture: Hybrid Research Assistant--- Private Core: local `llama-server` processes sensitive files.-- Public Edge: Gemini 1.5 Pro (via LangChain) handles broad reasoning and web context.-- Connective Tissue: SAM provides secure peer-to-peer discovery and A2A transport so private data paths stay under your control.--```text-Private Files -> Local MCP Tool (llama-server) -> Sanitized Summary ----+- |-Public Web/Data -> Public MCP (Firecrawl or docs source) -> Evidence ----+-> Gemini Synthesis- |- Orchestrated by LangChain --+-```--## Step 1: Spin Up the Private Brain (llama-server)--Start your local model service:--```bash-./llama-server -m ./models/llama-3-8b.gguf --port 8080 --webui-mcp-proxy-```--Publish that local MCP capability into SAM.--Important: in SAM, the access scope for files is enforced by your local MCP tool configuration, not by `sam publish` flags.--```bash-# Start a node for this workflow-sam up &--# Publish a private-docs capability backed by local MCP on :8080-sam publish mcp \- --capability private-docs \- --resource-name private-docs \- --resource-kind tool \- --port 8080-```--If you need a safety check before publishing network-visible state:--```bash-sam publish --skill private-docs --mcp-port 8080 --dry-run=client-```--## Step 2: Orchestrate with LangChain + Gemini--LangChain acts as the director:--- route private reads/summarization to local SAM capability-- route public retrieval to a public MCP/web source-- send only sanitized output to Gemini for final synthesis--Example scaffold:--```python-from langchain_google_genai import ChatGoogleGenerativeAI--# NOTE:-# - SAM CLI is request/response; for production orchestration, run a small adapter-# service that exposes SAM calls as an MCP server transport for LangChain.-# - The snippet below focuses on control flow, not adapter implementation details.--llm = ChatGoogleGenerativeAI(model="gemini-1.5-pro")--private_summary = """-[From local private-docs capability]-Contract summary (sanitized):-- no personal names-- no raw clauses copied-- extracted obligations and controls only-"""--public_evidence = """-[From public retrieval]-Latest EU AI Act obligations for high-risk systems...-"""--prompt = f"""-You are auditing compliance.--Private sanitized summary:-{private_summary}--Public legal evidence:-{public_evidence}--Return:-1) compliance gaps-2) required remediation-3) confidence and citations-"""--result = llm.invoke(prompt)-print(result.content)-```--## Step 3: End-to-End User Journey--1. Local Filter-The private document is processed locally by your `private-docs` capability. The output is sanitized (PII removed, trade secrets abstracted, sensitive literals redacted).--2. Public Search-Your public retrieval tool fetches current sources (official policy, docs, standards, legal text).--3. Sovereign Synthesis-Gemini receives only the sanitized private summary plus public evidence and generates the final audit report.--Result: high-quality analysis, with raw private source files never sent to cloud inference.--## Why This Pattern Wins--- Data residency by design: easiest path for GDPR/HIPAA-style constraints.-- Cost efficiency: local model does heavy extraction; cloud model does higher-value synthesis.-- Low infrastructure overhead: SAM supports direct peer connectivity without central gateway dependency.--## Security Controls Checklist--- Use a dedicated environment/profile for this workflow.-- Prefer least-privilege capabilities (`private-docs`, not broad wildcard tools).-- Use Biscuit caveats for tool restrictions (for example, allow only `private-docs`).-- Audit tokens and cards before execution:--```bash-sam inspect biscuit "auditor-bot;allow_skill=private-docs"-sam inspect card '{"peer_id":"...","agent_card":{...}}'-sam call private-docs --message "summarize" --dry-run=client-```--## BATS E2E Test Skeleton--```bash-@test "E2E: Hybrid audit keeps secret local" {- sam up &-- echo "Secret: Don't tell the cloud" > /tmp/secret.txt-- # Assume local MCP tool on :8080 is configured to read /tmp only- sam publish mcp \- --capability private-docs \- --resource-name private-docs \- --port 8080 &-- run python3 ./scripts/hybrid_test.py-- assert_output --partial "Summary of document"- refute_output --partial "Don't tell the cloud"-}-```--## Operational Notes--- `sam publish mcp` exposes an MCP endpoint reachable through SAM; it does not configure filesystem ACLs.-- Keep your local MCP implementation responsible for strict path allowlists.-- For reproducibility, pin model version and prompt templates used for sanitization.--## Next Steps--- Read [CLI Reference](../cli/reference.md) for exact command flags.-- Read [Biscuit Authorization](../concepts/biscuit.md) for capability caveats.-- Read [Testing Guide](../testing.md) to integrate this flow into CI.diff --git a/docs/index.html b/docs/index.htmlindex 53b89e37..122683f0 100644--- a/docs/index.html+++ b/docs/index.html@@ -72,7 +72,7 @@// Documentation settingsloadSidebar: true,loadNavbar: false,- coverpage: true,+ coverpage: false,auto2top: true,// Search plugindiff --git a/docs/quickstart.md b/docs/quickstart.mdindex dab4d20c..dd3301cb 100644--- a/docs/quickstart.md+++ b/docs/quickstart.md@@ -1,147 +1,64 @@-# Quick Start Reference+# Quick Start-## Installation+## Prerequisites++- Go toolchain+- Docker (for containerized e2e tests)+- BATS (`bats-core`)++## Build```bashgit clone https://github.com/aojea/sam.gitcd sammake build-./bin/sam-agent --help```-## First Steps (5 Minutes)+This creates:-### 1. Authenticate+- `./bin/sam-hub`+- `./bin/sam-node`-```bash-sam-agent identity login --hub https://identity.example.com-```+## Start Hub-### 2. Publish an Agent+`sam-hub` requires OIDC issuer settings and a 32-byte hex key seed.```bash-# Start a local MCP server on port 8080-sam-agent publish --skill my-skill --mcp-port 8080+SAM_OIDC_ISSUER=https://issuer.example.com \+SAM_OIDC_ID=sam-client \+SAM_OIDC_SECRET=sam-secret \+SAM_HUB_KEY=$(openssl rand -hex 32) \+./bin/sam-hub```-### 3. Call an Agent+## Login Node```bash-sam-agent call my-skill --message "Do something"+./bin/sam-node login --hub http://localhost:8080```----+The command prints a browser login URL and asks you to paste the identity biscuit token.-## Common Commands+## Run Node-### Mesh+Using stored identity:```bash-# Get visible agents-sam-agent mesh get agents--# Watch new agents in real time-sam-agent mesh get agents --watch+./bin/sam-node run```-### Identity+Or using explicit token:```bash-# Show current identity-sam-agent identity whoami--# Re-authenticate-sam-agent identity login --hub https://identity.example.com+./bin/sam-node run --token <identity-biscuit>```-### Publishing and Calling+## Test```bash-# Publish with dry-run (no network)-sam-agent publish --skill test --mcp-port 8080 --dry-run=client--# Call with dry-run (no network)-sam-agent call test --message "hello" --dry-run=client--# Call with custom Biscuit token-sam-agent call test --message "hello" --biscuit "user;allow_skill=test"+make test+make test-e2e+make test-e2e-container```-### Auditing--```bash-# Inspect a Biscuit token-sam-agent inspect biscuit "alice;allow_skill=weather-bot"--# Inspect an Agent Card-sam-agent inspect card '{"peer_id":"...","agent_card":{...}}'-```-------## Global Flags--```bash---debug Enable debug logging-```-------## File Locations--```-~/.config/sam/-βββ identity/-β βββ credentials.json (hub/device credentials and passport biscuit)-βββ federations/- βββ default.db (default mesh state database)-```-------## Troubleshooting--| Issue | Solution |-|-------|----------|-| "passport expired" | `sam-agent identity login --hub <url>` |-| "skill not allowed" | Check Biscuit token: `sam-agent inspect biscuit <token>` |-| "no peers found" | Publish agent first: `sam-agent publish --skill <name> --mcp-port <port>` |-| "connection timeout" | Check network: `sam-agent up --run-for 30s` |-------## Key Concepts--**Passport Biscuit**: Hub-issued identity credential bound to peer ID and default federation audience.--**Biscuit**: Skill-access credential, plain-text format `subject;allow_skill=X,Y,Z`.--**Agent Card**: Signed manifest of skills published to DHT.--**A2A**: Agent-to-agent RPC protocol over libp2p.-------## Documentation--- **[Overview](#/README.md)**: What SAM is and why it matters-- **[User Journey](#/guides/dark-mesh.md)**: Step-by-step walkthrough-- **[CLI Reference](#/cli/reference.md)**: Full command documentation-- **[Testing](#/testing.md)**: How to run and write tests-- **[FAQ](#/faq.md)**: Common questions-- **[Glossary](#/glossary.md)**: Terminology reference-------## Help--```bash-# Any command help-sam-agent <command> --help--# Verbose logging-SAM_DEBUG=1 sam-agent <command>--# Report bugs-https://github.com/aojea/sam/issues-```+`make test-e2e-container` runs hub + multiple node containers with a mock OIDC provider.diff --git a/docs/testing.md b/docs/testing.mdindex 5516de35..3f08f60b 100644--- a/docs/testing.md+++ b/docs/testing.md@@ -1,426 +1,80 @@-# Testing Guide: Validating SAM+# Testing-SAM has comprehensive test coverage across three levels:+Current testing is intentionally minimal and aligned with the current binaries.-1. **Unit Tests** (Go): Pure function testing-2. **Integration Tests** (Go): Multi-node scenarios with namespaces-3. **E2E Tests** (BATS): CLI validation and user workflows+## Test Layers----+1. Go tests: `make test`+2. BATS CLI tests: `make test-e2e`+3. Containerized BATS mesh tests: `make test-e2e-container`-## Test Architecture--### Test Isolation--Tests use **Linux user namespaces** to isolate network state:--```go-func TestA2ACall(t *testing.T) {- // Each test runs in CLONE_NEWNET namespace- // Network stack is isolated- // DHT doesn't interfere with other tests- testutils.Run(t, f, testutils.CLONE_NEWNET)-}-```--**Benefits:**--- No test pollution (each test has clean network)-- Can run tests in parallel-- Can simulate network conditions (no connectivity, firewall)-- Each test cleanup is automatic--### Test Levels--```-ββββββββββββββββββββββββββββββββββββββββββββ-β E2E Tests (BATS) β-β - CLI commands β-β - User workflows β-β - Dry-run and inspect β-ββββββββββββββββββββββββββββββββββββββββββββ- β-ββββββββββββββββββββββββββββββββββββββββββββ-β Integration Tests (Go) β-β - Multi-node scenarios β-β - DHT discovery β-β - A2A calls β-β - Federation isolation β-ββββββββββββββββββββββββββββββββββββββββββββ- β-ββββββββββββββββββββββββββββββββββββββββββββ-β Unit Tests (Go) β-β - Biscuit parsing β-β - Vouch verification β-β - Card encoding/decoding β-ββββββββββββββββββββββββββββββββββββββββββββ-```-------## Unit Tests--Unit tests validate individual components in isolation.--### Running Unit Tests+## Commands```bash-# Run all unit tests-go test ./...--# Run with race detection-go test -race ./...--# Run specific package-go test ./pkg/economy--# Run specific test-go test -run TestParseBiscuit ./pkg/economy--# Show coverage-go test -cover ./...--# Generate coverage report-go test -coverprofile=coverage.out ./...-go tool cover -html=coverage.out-```--### Key Test Files--| Package | Tests | Purpose |-|---------|-------|---------|-| `pkg/economy` | `TestParseBiscuit`, `TestCheckSkill` | Biscuit token parsing and skill verification |-| `pkg/protocol` | `TestAgentCard`, `TestDiscovery` | Agent card encoding/decoding, peer discovery |-| `pkg/net` | `TestNodeStart`, `TestDHT` | Node lifecycle, DHT initialization |-| `pkg/identity` | `TestVouchVerify`, `TestVouchExpiry` | Vouch signature and expiry checks |--### Example Unit Test--```go-func TestParseBiscuit(t *testing.T) {- parser := economy.SimpleBiscuitParser{}-- // Test simple biscuit- ctx := context.Background()- parsed, err := parser.Parse(ctx, "alice;allow_skill=weather-bot")-- if err != nil {- t.Fatalf("Parse failed: %v", err)- }- if parsed.Subject != "alice" {- t.Errorf("Expected subject 'alice', got %q", parsed.Subject)- }- if len(parsed.AllowedSkills) != 1 {- t.Errorf("Expected 1 skill, got %d", len(parsed.AllowedSkills))- }- if parsed.AllowedSkills[0] != "weather-bot" {- t.Errorf("Expected 'weather-bot', got %q", parsed.AllowedSkills[0])- }-}-```-------## Integration Tests--Integration tests validate multi-node scenarios with network isolation.--### Running Integration Tests--```bash-# Run all integration tests-go test -race -count=1 ./tests/integration--# Run specific test-go test -race -count=1 -run TestCUJ1 ./tests/integration--# Verbose output-go test -race -count=1 -v ./tests/integration--# Timeout (integration tests can take 30-60s)-go test -race -timeout=5m -count=1 ./tests/integration-```--### Key Integration Tests--| Test | Time | Purpose |-|------|------|---------|-| `TestCUJ1Stealth` | 45s | Federation DHT isolation (dark mesh) |-| `TestCUJ2HolePunch` | 60s | Relay-assisted connectivity (DCUtR) |-| `TestA2ACall` | 30s | Agent-to-agent RPC with Biscuit auth |-| `TestMeshDHT` | 40s | Multi-federation discovery |--### Example Integration Test--```go-func TestCUJ1StealthAudit(t *testing.T) {- // Run in isolated network namespace- testutils.Run(t, func(f *testutils.Framework) {- // Create two federations: alpha, beta- alphaA, _ := cujStartNode(t, f, "alpha", "alpha-a")- alphaB, _ := cujStartNode(t, f, "alpha", "alpha-b")- betaA, _ := cujStartNode(t, f, "beta", "beta-a")-- // Wait for DHT convergence- cujWaitDiscover(t, alphaA, alphaB.PeerID(), 10*time.Second)-- // Alpha agents should discover each other- _, err := alphaA.Discover(alphaB.PeerID())- if err != nil {- t.Fatalf("alphaA should discover alphaB: %v", err)- }-- // But Beta agent should NOT discover Alpha agents- // (federation isolation enforced at DHT level)- _, err = betaA.Discover(alphaA.PeerID())- if err == nil {- t.Fatalf("betaA should NOT discover alphaA (federation isolation)")- }- }, testutils.CLONE_NEWNET)-}-```--### Test Framework Helpers--The `testutils` package provides helpers for integration tests:--```go-// Start a node in a federation-node, _ := cujStartNode(t, f, federationID, nodeName)--// Wait for node to discover a peer-cujWaitDiscover(t, node, targetPeerID, timeout)--// Get relay circuit address for NAT traversal-circuit := cujRelayCircuitAddr(t, f, relayNode, targetNode)--// Wait for direct connection (DCUtR holepunch)-cujWaitForDirectConn(t, node1, node2, timeout)--// Bootstrap addresses-addrs := cujBootstrapAddrs(f, bootstrapNode)-```-------## E2E Tests (BATS)--E2E tests use BATS (Bash Automated Testing System) to validate CLI commands.--### Running E2E Tests--```bash-# Build binary firstmake build--# Run all E2E tests+make testmake test-e2e--# Run with verbose output-SAM_BINARY=./bin/sam bats --verbose-run tests/e2e/sam.bats--# Run specific test-SAM_BINARY=./bin/sam bats --filter "sam inspect" tests/e2e/sam.bats+make test-e2e-container```-### Key E2E Tests--| Test | Purpose |-|------|---------|-| `sam up --help` | Verify help output |-| `sam publish --help` | Verify publish command |-| `sam inspect biscuit` | Parse and explain Biscuit token |-| `sam publish --dry-run=client` | Build card without network |-| `sam call --dry-run=client` | Validate call without network |-| `sam inspect card` | Decode Agent Card JSON |+## Go Tests-### Example BATS Test+Run all Go tests with race detection:```bash-@test "sam inspect biscuit parses and explains a token" {- token="alice;allow_skill=risk-audit,weather-bot"- run "$SAM_BINARY" inspect biscuit "$token"-- # Assertion: command succeeded- [[ "$status" -eq 0 ]]-- # Assertion: output contains subject- [[ "$output" == *"alice"* ]]-- # Assertion: output contains skills- [[ "$output" == *"risk-audit"* ]]- [[ "$output" == *"weather-bot"* ]]-}+make test```-### BATS Syntax+Run only integration package:```bash-# Run command (output in $output, exit code in $status)-run "$SAM_BINARY" command arg1 arg2--# Assertions-[[ "$status" -eq 0 ]] # Exit code is 0 (success)-[[ "$output" == *"text"* ]] # Output contains text-[[ "$output" =~ ^regex$ ]] # Output matches regex-[[ ! "$output" =~ pattern ]] # Output does NOT match pattern+go test ./tests/integration/...```----+## BATS CLI Tests-## Running Full Test Suite+These tests validate current command behavior for:-### Quick Test Run+- `sam-node`+- `sam-hub`-```bash-# Unit tests only (fast, ~10s)-go test ./...--# With race detection-go test -race ./...-```--### Full Suite+Run:```bash-# Everything: unit + integration + E2E-make test--# What make test does:-# 1. go test -race -count=1 ./... (unit + integration, ~60s)-# 2. make build (compile binary)-# 3. bats tests/e2e/sam.bats (E2E tests, ~30s)-```--### Expected Output--```-go test -race -count=1 ./...-ok sam 89.234s (82 tests passed)--make build-go build -v -o ./bin/sam ./cmd/sam--SAM_BINARY=./bin/sam bats --verbose-run tests/e2e/sam.bats- β sam up --help returns success- β sam publish --help returns success- β sam inspect biscuit parses token- ...-12 tests, 0 failures+make test-e2e```------## Contributing: Test Requirements--When submitting a PR, ensure:--1. **All unit tests pass**- ```bash- go test -race ./...- ```+## Containerized Mesh BATS-2. **No race conditions**- ```bash- go test -race ./...- ```+The container framework is implemented in:-3. **All integration tests pass**- ```bash- go test -race -count=1 ./tests/integration- ```+- `tests/e2e/lib/container_mesh.bash`-4. **All E2E tests pass**- ```bash- make test-e2e- ```+It starts:-5. **New features have tests**- - Add unit test in same package- - Add integration test if multi-node- - Add BATS test if CLI-facing+1. mock OIDC container+2. `sam-hub` container+3. multiple `sam-node` containers-### Test Checklist+Run:```bash-# Before submitting PR-make test # Full suite-go test -race ./... # Explicit race check-go test -cover ./... # Check coverage+make test-e2e-container```------## Performance Testing--### Benchmarking+Optional image override:```bash-# Run benchmarks-go test -bench=. ./pkg/economy--# Benchmark with memory stats-go test -bench=. -benchmem ./pkg/economy--# CPU profile-go test -bench=. -cpuprofile=cpu.prof ./pkg/economy-go tool pprof cpu.prof--# Memory profile-go test -bench=. -memprofile=mem.prof ./pkg/economy-go tool pprof mem.prof-```--### Example Benchmark--```go-func BenchmarkParseBiscuit(b *testing.B) {- parser := economy.SimpleBiscuitParser{}- ctx := context.Background()- token := "alice;allow_skill=weather-bot,risk-audit"-- b.ResetTimer()- for i := 0; i < b.N; i++ {- _, _ = parser.Parse(ctx, token)- }-}+MESH_RUNTIME_IMAGE=sam-e2e-runtime:dev make test-e2e-container```------## Debugging Tests+## Troubleshooting-### Verbose Output+- Ensure Docker daemon is running before container tests.+- Ensure `bats` is installed and available in `PATH`.+- If a test fails, inspect containers:```bash-# See all log output-go test -v ./tests/integration--# With debug flag-SAM_DEBUG=1 go test -v ./...-```--### GDB Debugging--```bash-# Run test with GDB-dlv test ./pkg/protocol -- -test.run TestAgentCard-```--### Print Debugging--```go-import "fmt"--func TestExample(t *testing.T) {- fmt.Printf("Debug: value=%v\n", someValue)-}+docker ps -a+docker logs <container-name>```-------## Next Steps--- **[Quick Start](#/guides/dark-mesh.md)**: Set up SAM locally-- **[CLI Reference](#/cli/reference.md)**: Test with real commands-- **[Contributing](#/contributing.md)**: Submit a test PR