multi-agent-protocol 0.0.4 → 0.1.0

package/docs/07-federation.md

@@ -206,18 +206,94 @@ Sensitive computation isolated in secure system, federated for I/O.
 
 ---
 
+## Single-Request Federation Auth
+
+Federation connection can be completed in a single round-trip by including auth credentials in the initial `map/federation/connect` request. When the server can validate the credentials immediately, it returns a fully authenticated response — reducing setup from 2 RTT to 1 RTT.
+
+### Flow: Single-Request Auth (Optimized)
+
+```
+System A                                      System B
+   │                                              │
+   │──── map/federation/connect ─────────────────►│
+   │     { systemId, endpoint, auth: { ... } }    │
+   │                                              │ ← Validates auth inline
+   │◄─── response ────────────────────────────────│
+   │     { connected: true, sessionId, principal } │
+   │                                              │
+```
+
+### Flow: Auth Negotiation Fallback
+
+If no credentials are provided, or validation fails recoverably, the server returns auth requirements:
+
+```
+System A                                      System B
+   │                                              │
+   │──── map/federation/connect ─────────────────►│
+   │     { systemId, endpoint }                   │
+   │                                              │
+   │◄─── response ────────────────────────────────│
+   │     { connected: false,                      │
+   │       authRequired: { methods, challenge } } │
+   │                                              │
+   │──── map/federation/connect ─────────────────►│
+   │     { systemId, endpoint, auth: { ... },     │
+   │       authContext: { challenge } }            │
+   │                                              │
+   │◄─── response ────────────────────────────────│
+   │     { connected: true, sessionId, principal } │
+   │                                              │
+```
+
+---
+
 ## Security Considerations
 
 ### Authentication
 
 ```typescript
+type FederationAuthMethod =
+  | "bearer" | "api-key" | "mtls" | "none"
+  | "did:wba" | "oauth2" | `x-${string}`;
+
 type MAPFederationAuth =
-  | { method: "mutual-tls"; certificate: string }
-  | { method: "bearer"; token: string }
-  | { method: "api-key"; key: string }
-  | { method: "oauth2"; config: OAuth2Config };
+  | { method: FederationAuthMethod; credentials?: string; metadata?: Record<string, unknown> }
+  | DIDWBACredentials;
+
+interface DIDWBACredentials {
+  method: "did:wba";
+  metadata: { did: string; proof: DIDWBAProof };
+}
 ```
 
+#### `did:wba` — Decentralized Identity for Federation
+
+The `did:wba` method enables domain-anchored decentralized identity for federation. An identity like `did:wba:agents.example.com:gateway` resolves to a DID document at `https://agents.example.com/gateway/did.json` containing public keys and MAP service endpoints.
+
+**Authentication flow:**
+1. Connecting system provides its DID and a cryptographic proof (ECDSA P-256 over challenge nonce)
+2. Receiving system resolves the DID document via HTTPS
+3. Receiving system verifies the proof against the public key in the DID document
+4. On success, the connecting system is authenticated as the DID principal
+
+```json
+{
+  "method": "did:wba",
+  "metadata": {
+    "did": "did:wba:agents.example.com:gateway",
+    "proof": {
+      "type": "JsonWebSignature2020",
+      "created": "2026-02-10T12:00:00.000Z",
+      "challenge": "map_chal_01ABCDEFGHJ0123456789AB",
+      "jws": "eyJhbGciOi..."
+    }
+  }
+}
+```
+
+See `docs/09-authentication.md` for full details on all auth methods including `did:wba`, and `docs/11-anp-inspired-improvements.md` Proposal 1 for the design rationale.
+
 ### Message Signing
 
 ```typescript
@@ -253,7 +329,7 @@ interface MAPFederationQueueConfig {
 ## Open Questions
 
 1. **Transitive federation**: If A↔B and B↔C, can A route to C via B?
-2. **Federation discovery**: Should there be a discovery mechanism for finding peers?
+2. ~~**Federation discovery**: Should there be a discovery mechanism for finding peers?~~ — Partially addressed by `did:wba` (DID document service endpoints) and proposed `.well-known` discovery (see `docs/11-anp-inspired-improvements.md` Proposal 2).
 3. **Consistency**: How to handle concurrent updates across federated systems?
 4. **Schema versioning**: What if peers have different protocol versions?
 5. **Audit requirements**: What federation activity must be logged?

package/docs/09-authentication.md

@@ -22,6 +22,7 @@ MAP defines the following standard authentication methods:
 | `bearer` | Bearer token (JWT or opaque) | OAuth2, IdP integration, M2M tokens |
 | `api-key` | Simple API key | Simple integrations, internal services |
 | `mtls` | Mutual TLS (transport layer) | High-security service-to-service |
+| `did:wba` | DID-based, domain-anchored | Cross-org federation, open discovery |
 
 ### Extension Methods
 
@@ -384,6 +385,54 @@ For trusted local connections.
 - Reject `none` based on transport type (e.g., require auth for WebSocket)
 - Assign a default principal for anonymous connections
 
+### DID:WBA (`did:wba`)
+
+Domain-anchored decentralized identity based on the W3C `did:wba` method. Identity is derived from domain ownership: a DID like `did:wba:agents.example.com:gateway` resolves to a DID document hosted at `https://agents.example.com/gateway/did.json`.
+
+**Credential format:** DID and cryptographic proof in metadata
+
+```typescript
+{
+  "method": "did:wba",
+  "metadata": {
+    "did": "did:wba:agents.example.com:gateway",
+    "proof": {
+      "type": "JsonWebSignature2020",
+      "created": "2026-02-10T12:00:00.000Z",
+      "challenge": "map_chal_01ABCDEFGHJ0123456789AB",
+      "jws": "base64url-encoded-ecdsa-signature"
+    }
+  }
+}
+```
+
+**DID Document:** The resolved DID document MUST contain:
+- `verificationMethod` with the public key used to verify the proof
+- `authentication` referencing the verification method
+- Optionally, a `service` entry of type `MAPFederationEndpoint` with the MAP WebSocket URL
+
+**Proof verification:**
+1. Server generates a challenge nonce (format: `map_chal_<ULID>`)
+2. Client signs `challenge.did.created` using ECDSA P-256 with its private key
+3. Server resolves DID → fetches DID document → extracts public key
+4. Server verifies the JWS signature against the public key and checks proof freshness
+
+**Security considerations:**
+- DID documents are fetched over HTTPS — domain ownership proves identity
+- Proof freshness is enforced via the `created` timestamp (default max age: 5 minutes)
+- Servers MAY maintain a trusted domains list to restrict accepted DIDs
+- DID document caching with configurable TTL prevents excessive lookups
+
+**When to use:**
+- Cross-organization federation where pre-shared credentials are impractical
+- Open discovery scenarios where peers find each other via DID documents
+- Systems that need globally unique, verifiable agent identities
+
+**SDK support:**
+- `DIDWBAAuthenticator` — server-side authenticator (see `ts-sdk/src/server/auth/did-wba-authenticator.ts`)
+- `generateDIDWBAProof()` / `verifyDIDWBAProof()` — proof utilities (see `ts-sdk/src/federation/did-wba/proof.ts`)
+- `DIDWBAResolver` — DID document resolution with caching (see `ts-sdk/src/federation/did-wba/resolver.ts`)
+
 ---
 
 ## Token Refresh
@@ -670,6 +719,25 @@ const server = new MAPServer({
 });
 ```
 
+### Example 5: Federation Server with DID:WBA
+
+```typescript
+import { DIDWBAAuthenticator } from '@anthropic/multi-agent-protocol/server/auth';
+
+const server = new MAPServer({
+  auth: {
+    required: true,
+    methods: ['did:wba', 'bearer'],
+    authenticators: [
+      new DIDWBAAuthenticator({
+        trustedDomains: ['*.example.com', 'partner.org'],
+      }),
+      new JWTAuthenticator({ /* ... */ })
+    ]
+  }
+});
+```
+
 ---
 
 ## Open Questions

package/docs/10-environment-awareness.md

@@ -0,0 +1,242 @@
+# Environment Awareness
+
+## Overview
+
+Environment awareness enables agents to advertise and discover information about their compute environments. This facilitates intelligent task routing, filesystem coordination, and resource-aware scheduling in heterogeneous multi-agent systems.
+
+## Motivation
+
+Agents may run across diverse environments:
+- Different mount points (Agent A at `/home/user/project`, Agent B at `/workspace/project`)
+- Different compute types (local, Docker, Kubernetes, cloud sandbox)
+- Different capabilities (GPU, specific tools, network access)
+- Different constraints (memory limits, ephemeral storage, execution timeouts)
+
+Environment awareness enables:
+- **Task routing**: Send GPU workloads to GPU-enabled agents
+- **Filesystem coordination**: Detect shared mounts vs. need for explicit file transfer
+- **Resource optimization**: Choose agents based on cost, latency, or capacity
+- **Security boundaries**: Route sensitive data to appropriately isolated agents
+
+## Schema
+
+The `AgentEnvironment` type uses a layered approach:
+
+- **Layer 1 (Normative)**: Category names are standardized
+- **Layer 2 (Conventions)**: Field names within categories are recommended patterns
+- **Layer 3 (Extensions)**: Custom fields allowed via `additionalProperties`
+
+```typescript
+interface AgentEnvironment {
+  schemaVersion?: string;      // Schema version (e.g., "1.0")
+  profiles?: string[];         // Self-declared compliance (e.g., ["cloud-native"])
+
+  // Standard categories (all optional, all extensible)
+  host?: Record<string, unknown>;       // CPU, memory, GPU
+  os?: Record<string, unknown>;         // OS type, version
+  process?: Record<string, unknown>;    // PID, cwd, runtime
+  container?: Record<string, unknown>;  // Container runtime info
+  cloud?: Record<string, unknown>;      // Provider, region, instance type
+  k8s?: Record<string, unknown>;        // Kubernetes context
+  filesystem?: Record<string, unknown>; // Mounts, workspace, VCS
+  network?: Record<string, unknown>;    // Connectivity, addresses
+  tools?: Record<string, unknown>;      // Installed tools, runtimes
+  resources?: Record<string, unknown>;  // Limits and constraints
+  security?: Record<string, unknown>;   // Isolation, compliance
+  services?: Record<string, unknown>;   // External APIs, MCP servers
+
+  [key: string]: unknown;  // Additional categories allowed
+}
+```
+
+## Common Field Conventions
+
+These field names are **recommended** (not required) for interoperability:
+
+| Category | Common Fields |
+|----------|--------------|
+| `host` | `arch`, `cpuCount`, `memoryBytes`, `gpu.count`, `gpu.models` |
+| `os` | `type` (linux/darwin/windows), `version`, `name` |
+| `process` | `pid`, `cwd`, `runtimeName`, `runtimeVersion` |
+| `cloud` | `provider`, `region`, `instanceType`, `accountId` |
+| `network` | `connectivity` (full/restricted/internal/isolated), `addresses` |
+| `filesystem` | `cwd`, `mounts`, `workspace.root`, `workspace.vcs`, `workspace.branch` |
+| `tools` | `installed`, `shell`, `runtimes`, `canInstall` |
+| `resources` | `cpuLimit`, `memoryLimitBytes`, `maxExecutionSeconds`, `costProfile` |
+| `security` | `isolation`, `privileged`, `sandbox`, `dataResidency` |
+| `services` | `aiProviders`, `mcp` (MCP servers) |
+
+## Protocol Integration
+
+### Agent Registration
+
+```typescript
+await connection.register({
+  name: 'my-agent',
+  environment: {
+    schemaVersion: '1.0',
+    os: { type: 'linux', version: '22.04' },
+    process: { cwd: '/home/user/project' },
+    network: { connectivity: 'full' },
+    tools: {
+      installed: { python: '3.11', node: '20.0' },
+      shell: 'bash'
+    }
+  }
+});
+```
+
+### Connect Response
+
+Servers can advertise their environment:
+
+```typescript
+interface ConnectResponse {
+  // ... existing fields
+  serverEnvironment?: AgentEnvironment;
+}
+```
+
+### Environment Updates
+
+Agents can update their environment via `map/agents/update`:
+
+```typescript
+await connection.update({
+  agentId: myAgentId,
+  environment: {
+    resources: { memoryLimitBytes: 8589934592 }  // Updated
+  }
+});
+```
+
+### Event: `agent_environment_changed`
+
+Emitted when an agent's environment changes:
+
+```typescript
+{
+  type: 'agent_environment_changed',
+  data: {
+    agentId: 'agent-123',
+    environment: { /* current */ },
+    previousEnvironment: { /* previous */ }
+  }
+}
+```
+
+### Subscription Filtering
+
+Filter events by environment attributes:
+
+```typescript
+await client.subscribe({
+  filter: {
+    eventTypes: ['agent_registered'],
+    environmentMatch: {
+      'os.type': 'linux',
+      'cloud.provider': 'aws'
+    }
+  }
+});
+```
+
+## Extension Patterns
+
+### Adding fields to categories
+
+```json
+{
+  "host": {
+    "arch": "arm64",
+    "memoryBytes": 17179869184,
+    "x-apple-silicon": { "chip": "M2 Pro" }
+  }
+}
+```
+
+### Adding new categories
+
+```json
+{
+  "schemaVersion": "1.0",
+  "os": { "type": "linux" },
+  "x-anthropic-sandbox": {
+    "sandboxId": "sb-abc123",
+    "tier": "premium"
+  }
+}
+```
+
+### Services with custom providers
+
+```json
+{
+  "services": {
+    "aiProviders": {
+      "huggingface": { "available": true, "tier": "pro" },
+      "openai": { "available": true }
+    },
+    "mcp": {
+      "filesystem": { "available": true, "tools": ["read_file", "write_file"] }
+    },
+    "x-internal": {
+      "userService": { "available": true }
+    }
+  }
+}
+```
+
+## Use Cases
+
+### Task Routing by Capability
+
+```typescript
+const agents = await client.agents.list();
+const gpuAgent = agents.find(a =>
+  a.environment?.host?.gpu?.count > 0
+);
+if (gpuAgent) {
+  await client.send({ to: gpuAgent.id, payload: mlTask });
+}
+```
+
+### Filesystem Coordination
+
+```typescript
+// Check if agents share a filesystem
+const myMounts = myAgent.environment?.filesystem?.mounts ?? {};
+const peerMounts = peerAgent.environment?.filesystem?.mounts ?? {};
+
+const sharedMount = Object.keys(myMounts).find(name =>
+  myMounts[name]?.shared && peerMounts[name]?.shared
+);
+
+if (sharedMount) {
+  // Can use file paths directly
+} else {
+  // Need to transfer file contents via messages
+}
+```
+
+### Network-Aware Routing
+
+```typescript
+const agents = await client.agents.list();
+const internetAgent = agents.find(a =>
+  a.environment?.network?.connectivity === 'full'
+);
+// Route external API calls through this agent
+```
+
+## Security Considerations
+
+1. **Sensitive data**: Filter environment variables before exposing (no API keys, tokens)
+2. **Opt-in exposure**: Agents explicitly choose what to advertise
+3. **Visibility rules**: Environment respects existing MAP visibility/permissions
+4. **Trust boundaries**: Don't implicitly trust environment claims from untrusted agents
+
+## References
+
+- [OpenTelemetry Resource Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/resource/)
+- [Kubernetes Node Feature Discovery](https://kubernetes-sigs.github.io/node-feature-discovery/)