Add rfc22 + rfc23 support

[nirvanatikku]

v0.14.0 — Federation Protocol & Security

Summary

Adds RFC-0022 (Federation Protocol) and RFC-0023 (Federation Security), providing cross-server agent coordination with cryptographic identity, signed envelopes, UCAN delegation tokens, and trust policy enforcement. Includes a complete Python SDK implementation, Express.js endpoints, MCP tools, and documentation across the website and reference implementation docs site.

What's New

Protocol Specifications

• RFC-0022: Federation Protocol — Defines the federation contract: envelope format, agent visibility (public/unlisted/private), peer relationships (peer/upstream/downstream), callbacks with at-least-once delivery, intent authority model, delegation scope with UCAN-style attenuation, governance propagation (strictest-wins), federation attestation (OpenTelemetry conventions), discovery via /.well-known/openintent-federation.json, and federation-aware leasing.
• RFC-0023: Federation Security — Layers authentication, authorization, and verification onto federation: server identity via did:web, signed envelopes (HTTP Message Signatures, RFC 9421), UCAN delegation tokens with attenuation and expiry, trust policies (open/allowlist/trustless), agent access policies, signed attestations, and cross-server event log reconciliation via RFC-0019 Merkle primitives.

Python SDK — 5-Layer Federation Implementation

Layer	Module	Contents
Models	openintent/federation/models.py	FederationEnvelope, FederationCallback, FederationPolicy, FederationAttestation, DelegationScope, FederationManifest, FederationStatus, DispatchResult, ReceiveResult, FederatedAgent, PeerInfo. Enums: AgentVisibility, PeerRelationship, TrustPolicy, CallbackEventType, DispatchStatus.
Client	openintent/client.py	federation_status(), list_federated_agents(), federation_dispatch(), federation_receive(), send_federation_callback(), federation_discover() — sync and async variants.
Server	openintent/server/federation.py	FastAPI router: GET /status, GET /agents, POST /dispatch, POST /receive, GET /.well-known/openintent-federation.json, GET /.well-known/did.json. SSRF validation, callback delivery with retry, governance enforcement, idempotency keys.
Security	openintent/federation/security.py	ServerIdentity (Ed25519, did:web), sign_envelope()/verify_envelope_signature(), MessageSignature (RFC 9421), TrustEnforcer (open/allowlist/trustless), UCANToken (create/encode/decode/attenuate), resolve_did_web(), validate_ssrf().
Decorators	openintent/federation/decorators.py	@Federation (class decorator), federation_visibility on @Agent, federation_policy on @Coordinator, lifecycle hooks: @on_federation_received, @on_federation_callback, @on_budget_warning.

Express.js Server

• 4 REST endpoints: GET /api/v1/federation/status, GET /api/v1/federation/agents, POST /api/v1/federation/dispatch, POST /api/v1/federation/receive
• Federation audit trail: dispatch IDs, provenance in state._federation, RFC-0020 trace propagation
• origin_server_url field on agent_records table for federated agents

MCP Tools

• 4 new tools: federation_status (read), list_federated_agents (read), federation_dispatch (admin), federation_receive (admin)
• Tool surface: 62 → 66 tools. RBAC counts: reader 23, operator 40, admin 66.

Federation Event Types

FEDERATION_DISPATCHED, FEDERATION_RECEIVED, FEDERATION_CALLBACK, FEDERATION_BUDGET_WARNING, FEDERATION_COMPLETED, FEDERATION_FAILED

Key Algorithms

• DelegationScope.attenuate() — Scope narrowing per hop: intersection of permissions, union of denied operations, minimum delegation depth.
• FederationPolicy.compose_strictest() — Strictest-wins governance: minimum for numerics, OR for booleans, merge for observability.

Documentation

• Website — Federation sections added to all 5 pages: Docs, API Reference, Agents, Examples, Adapters.
• Docs site (MkDocs) — Rebuilt with federation content:
  • guide/federation.md — Concepts, configuration, code examples
  • examples/federation.md — Runnable examples for dispatch, signing, UCAN, trust enforcement
  • api/federation.md — Complete class and method reference
  • rfcs/0022-federation-protocol.md — Full RFC specification
  • rfcs/0023-federation-security.md — Full RFC specification
• Changelog updated with links to all new pages.
• Homepage updated: 23 RFCs, 800+ tests, v0.14.0, federation feature cards.

Discovery & Compatibility

• /.well-known/openintent.json — federation capability added, RFC-0022/0023 in rfcUrls
• /.well-known/openintent-compat.json — RFC-0022 (full), RFC-0023 (partial)
• /.well-known/openintent-federation.json — New federation discovery endpoint
• /.well-known/did.json — DID document for server identity

Tests

• 82 new federation tests covering:
  • Model serialization round-trips
  • Security: sign/verify, UCAN create/encode/decode/attenuate, SSRF blocking, trust enforcement
  • Server endpoints via TestClient + SQLite
  • Decorator configuration and lifecycle hooks
  • Integration flows (dispatch → receive → callback)

Breaking Changes

None. Federation is additive — existing APIs and behavior are unchanged. Federation operates in trusted mode by default; RFC-0023 security is opt-in.

Files Changed

New files (click to expand)

reference-implementation/openintent/federation/__init__.py
reference-implementation/openintent/federation/models.py
reference-implementation/openintent/federation/security.py
reference-implementation/openintent/federation/decorators.py
reference-implementation/openintent/server/federation.py
reference-implementation/docs/guide/federation.md
reference-implementation/docs/examples/federation.md
reference-implementation/docs/api/federation.md
reference-implementation/docs/rfcs/0022-federation-protocol.md
reference-implementation/docs/rfcs/0023-federation-security.md
reference-implementation/tests/test_federation_models.py
reference-implementation/tests/test_federation_security.py
reference-implementation/tests/test_federation_server.py
reference-implementation/tests/test_federation_decorators.py

Modified files (click to expand)

reference-implementation/openintent/__init__.py          # version bump, federation exports
reference-implementation/openintent/client.py            # 6 federation client methods (sync + async)
reference-implementation/pyproject.toml                  # version 0.14.0
reference-implementation/mkdocs.yml                      # nav, announcement, metadata updates
reference-implementation/docs/overrides/home.html        # hero, stats, feature cards, RFC table
reference-implementation/docs/changelog.md               # v0.14.0 entry
reference-implementation/mcp-server/package.json         # version 0.14.0
reference-implementation/mcp-server/src/index.ts         # 4 federation MCP tools
client/src/pages/docs.tsx                                # Federation section
client/src/pages/reference.tsx                           # RFC-0022 & RFC-0023 sections
client/src/pages/agents.tsx                              # Federation decorators & capabilities
client/src/pages/examples.tsx                            # Cross-Server Federation example
client/src/pages/adapters.tsx                            # Federation table rows
client/src/pages/changelog.tsx                           # v0.14.0 entry with doc links
server/routes.ts                                         # federation endpoints, discovery updates
shared/schema.ts                                         # origin_server_url field