🌱 seed-chat — Inter-Fleet Messaging

Fleet-to-fleet chat with Ed25519 signing, channel management, quarantine for unknown senders, and Server-Sent Events (SSE) streaming.

What It Does

This seed gives your fleet a public inbox (POST /fleet-chat/inbox) that other fleets can send messages to. Incoming messages from trusted contacts go straight into a channel; messages from unknown senders are quarantined until you approve or reject them. Every message is signed — with a real Ed25519 key when available, or a SHA-256 HMAC hash for development.

Key Concepts

Concept	Description
Channel	A conversation between your fleet and one remote fleet
Trusted Endpoint	A remote fleet identity (name + endpoint + publicKey) you trust
Quarantine	Messages from unknown senders held for review
Fleet Identity	{ name, endpoint, publicKey } — your fleet's calling card

How to Plant

1. Paste this repo (or just src/store.ts + src/routes.ts) into any AI agent with access to a Node.js runtime.
2. Tell the agent: "Plant this seed. Set up fleet-chat as an HTTP service."
3. The agent reads the protocol, adapts store.ts and routes.ts to your stack, and starts the service.

Quick Start (if you have Node.js + Hono)

# Copy src/ into your project
cp -r src/* your-project/src/fleet-chat/

# Wire routes in your server.ts:
#   Public (no auth):  app.route("/fleet-chat", fleetChatPublicRoutes)
#   Authenticated:     app.route("/fleet-chat", fleetChatRoutes)

# Set your fleet identity:
curl -X POST http://localhost:3000/fleet-chat/identity \
  -H "Content-Type: application/json" \
  -d '{"name":"my-fleet","endpoint":"https://my-fleet.example.com","publicKey":"pk-placeholder"}'

Protocol

Public Endpoints (no auth — other fleets call these)

Method	Path	Description
POST	/fleet-chat/inbox	Receive a message from another fleet
GET	/fleet-chat/inbox/stream	SSE stream of incoming messages

Authenticated Endpoints (bearer token)

Method	Path	Description
POST/GET	/fleet-chat/identity	Set/get local fleet identity
POST/GET	/fleet-chat/channels	Create/list channels
GET/PATCH	/fleet-chat/channels/:id	Get/update channel
POST/GET	/fleet-chat/channels/:id/messages	Send/get messages (SSE supported)
GET/POST/DELETE	/fleet-chat/trusted	Manage trusted endpoints
GET	/fleet-chat/quarantine	List quarantined messages
POST	/fleet-chat/quarantine/:id/approve	Approve (adds sender to trusted)
POST	/fleet-chat/quarantine/:id/reject	Reject and discard

Message Format (POST /fleet-chat/inbox)

{
  "from": { "name": "remote-fleet", "endpoint": "https://remote.example.com", "publicKey": "..." },
  "to": { "name": "my-fleet", "endpoint": "https://my-fleet.example.com", "publicKey": "..." },
  "type": "text",
  "content": "Hello from my fleet!",
  "timestamp": "2026-02-15T00:00:00.000Z",
  "signature": "<sha256-or-ed25519-signature>"
}

How to Verify

# 1. Health: identity is set
curl http://localhost:3000/fleet-chat/identity

# 2. Create a channel
curl -X POST http://localhost:3000/fleet-chat/channels \
  -H "Content-Type: application/json" \
  -d '{"remoteFleet":{"name":"test","endpoint":"https://test.example.com","publicKey":"pk-test"}}'

# 3. Send a message on the channel
curl -X POST http://localhost:3000/fleet-chat/channels/<CHANNEL_ID>/messages \
  -H "Content-Type: application/json" \
  -d '{"content":"Hello!"}'

# 4. Receive an inbound message via the public inbox
curl -X POST http://localhost:3000/fleet-chat/inbox \
  -H "Content-Type: application/json" \
  -d '{"from":{"name":"friend","endpoint":"https://friend.example.com","publicKey":"pk-friend"},"to":{"name":"my-fleet","endpoint":"https://my-fleet.example.com","publicKey":"pk-placeholder"},"type":"text","content":"hey!","timestamp":"2026-02-15T00:00:00Z","signature":"placeholder"}'
# → 202 (quarantined) or 200 (if sender is trusted)

# 5. Run tests
npx vitest run

File Structure

seed-chat/
├── seed.yaml              # Seed manifest (v0.3.1 spec)
├── README.md              # This file
├── src/
│   ├── store.ts           # FleetChatStore — channels, messages, crypto, quarantine
│   └── routes.ts          # Hono routes — public inbox + authenticated management
└── tests/
    ├── store.test.ts      # Store unit tests (identity, channels, messages, quarantine, crypto)
    └── routes.test.ts     # Route integration tests

Extracted From

Reference implementation running in production on the HD Research fleet (vers-agent-services/src/fleet-chat/). Tested with real fleet-to-fleet messaging between Noah's fleet and external collaborators.

License

CC-BY-4.0