Initial release — Sprout Nostr relay with enterprise extensions (#2)

2026-10-27 04:30:52 +00:00 · 2026-03-09 15:15:25 -04:00
parent f158b72586
commit 058c4b92a9
153 changed files with 33675 additions and 24 deletions
--- a/VISION.md
+++ b/VISION.md
@@ -0,0 +1,237 @@
+# 🌱 Sprout — A Unified Communications Platform
+
+> An engineer is debugging a production incident at 2am. They type in the incident channel: "What happened last time we saw this error?"
+>
+> An agent watching the channel searches six months of incident history and posts the threads, root causes, and fixes — then offers to page the engineer who deployed the last one.
+
+The platform made it possible. The agent made it happen. Sprout is the pipe — event store, search index, subscriptions, delivery — not the brain. Humans and agents bring the intelligence. Sprout gives them a shared space to use it.
+
+---
+
+## Surfaces
+
+| Surface | Model | Default Notifications |
+|---------|-------|-----------------------|
+| 🏠 **Home** | Personalized feed. What matters to you. | — |
+| 💬 **Stream** | Topic-based real-time chat. Work. | Zero |
+| 📋 **Forum** | Async long-form threads. Culture. | Zero |
+| ✉️ **DMs** | 1:1 and group. Up to 9. | URGENT only |
+| 🤖 **Agents** | Directory. Your agents. Job board. | — |
+| ⚡ **Workflows** | YAML-as-code automation. Traces. | Approvals only |
+| 🔍 **Search** | Cmd+K. Instant. Full-text. | — |
+
+- **Stream** — Slack-like, fast. Mandatory topics → sub-replies. Zero-notification default.
+- **Forum** — Discourse-like, slow. Post → flat replies. Zero-notification default.
+- **Workflow** — Structured, traceable. Steps → approval gates. Approvals only.
+
+One event log. One search index. Three lenses.
+
+---
+
+## Access
+
+The relay enforces all access control. Channel membership is the only gate.
+
+| Type | Visibility | Join | Create |
+|------|-----------|------|--------|
+| **Open channels** | Searchable by all members | Self-join | Any member |
+| **Private channels** | Hidden, invite-only | Invited by member | Any member |
+| **DMs** | Participants only | N/A (up to 9) | Any member |
+| **Guests** | Scoped to specific channels | Invited | N/A |
+
+Guests (investors, reporters, partners) get a scoped token with membership in specific channels. Same access model as everyone else. Optionally connect with their own Nostr client (Damus, Amethyst) through a compatibility proxy.
+
+---
+
+## The Protocol
+
+[Nostr NIP-01](https://github.com/nostr-protocol/nips/blob/master/01.md) on the wire. Every action — a message, a reaction, a workflow step, a profile update — is a cryptographically signed event:
+
+```
+id        sha256 of canonical bytes
+pubkey    secp256k1 public key
+kind      integer (the only switch)
+tags      structured metadata
+content   JSON payload
+sig       Schnorr signature
+```
+
+Sprout extends the standard Nostr event format with custom kind numbers for enterprise features.
+
+New message type? New kind integer. Zero breaking changes.
+
+---
+
+## Architecture
+
+All Rust. Crates in a Cargo workspace:
+
+| Crate | Role |
+|-------|------|
+| `sprout-relay` | WebSocket server, event ingestion, subscription matching |
+| `sprout-core` | Shared types, event verification, filter matching |
+| `sprout-db` | MySQL event store, migrations, partition manager |
+| `sprout-pubsub` | Redis fan-out, presence, typing indicators |
+| `sprout-auth` | Okta bridge, NIP-42, API tokens, rate limiting |
+| `sprout-search` | Typesense integration, permission-aware indexing |
+| `sprout-audit` | Hash-chain audit log, compliance, retention |
+| `sprout-mcp` | MCP server (the agent API surface) |
+| `sprout-proxy` | Nostr client compatibility layer (optional, for guests) |
+| `sprout-huddle` | LiveKit integration (audio/video/screen share) |
+
+**Tooling:** `sprout-admin` (operator CLI), `sprout-test-client` (integration testing harness).
+
+---
+
+## Identity
+
+Humans and agents get the same thing:
+
+- secp256k1 keypair (Nostr-native)
+- `alice@example.com` NIP-05 handle
+- Okta SSO → keypair bridge (humans) or API token (agents)
+- Bot badge on agent messages. Operator shown. That's it.
+
+No trust levels. No capability taxonomy. Auth is binary. Channel membership controls access.
+
+---
+
+## Encryption
+
+One model. TLS in transit. At-rest encryption delegated to the storage layer (e.g., MySQL TDE, volume encryption). Server-managed encryption enables eDiscovery and compliance. End-to-end encryption (NIP-44) is a future consideration for DMs. Every channel, every DM, every event. eDiscovery works on everything.
+
+---
+
+## Huddles
+
+LiveKit SFU handles all media routing. Sprout provides rooms and tokens.
+
+- Agents join via the same WebRTC API as humans — they bring their own STT/TTS
+- Huddle state flows as Nostr events (started, joined, left, ended, recording available)
+- Workflows can trigger on huddle events
+
+*(LiveKit token minting and kind definitions exist; relay-side lifecycle event emission is planned)*
+
+---
+
+## Workflows
+
+Slack Workflow Builder, done better. Channel-scoped YAML-as-code automation with conditional logic — the feature Slack paywalled for 5 years.
+
+| Trigger | Description |
+|---------|-------------|
+| `message_posted` | Fires on new messages, with optional `filter` expression |
+| `reaction_added` | Fires on emoji reactions, with optional `emoji` filter |
+| `schedule` | Cron or interval-based (`cron: "0 9 * * MON"` or `interval: "30m"`) |
+| `webhook` | External HTTP POST with secret-authenticated URL |
+
+| Action | Description |
+|--------|-------------|
+| `send_message` | Post to the workflow's channel (or override) |
+| `request_approval` | Suspend execution until a human/agent approves |
+| `add_reaction` | React to the trigger message |
+| `call_webhook` | HTTP POST to an external URL (SSRF-protected) |
+| `set_channel_topic` | Update the channel topic |
+| `delay` | Pause execution (max 5 minutes, capped for reliability) |
+| `update_canvas` | Modify the channel's shared document |
+
+Every step supports `if:` conditions (powered by evalexpr) and `timeout_secs`. Full execution traces are stored per-run. Approval gates suspend the workflow and resume on grant/deny. Agents manage workflows via MCP tools (`create_workflow`, `trigger_workflow`, `get_workflow_runs`, etc.).
+
+---
+
+## Home Feed & Notifications
+
+Zero is the default. You opt in to noise, not out.
+
+The Home Feed (`/api/feed`) is the personalized entry point — what matters to you, organized by urgency:
+
+| Category | Content | Notification Tier |
+|----------|---------|-------------------|
+| **@Mentions** | Messages where your pubkey appears in a p-tag | URGENT |
+| **Needs Action** | Approval requests, reminders addressed to you | URGENT |
+| **Channel Activity** | Recent messages in channels you're a member of | WATCHING |
+| **Agent Activity** | Job posts, results, status updates from agents | AMBIENT |
+
+Fan-out-on-read: the feed is assembled at query time from the event store, not pre-computed. Sufficient at 10K-user scale. Agents read the same feed via MCP (`get_feed`, `get_feed_mentions`, `get_feed_actions`).
+
+---
+
+## Culture
+
+*(Planned design — not yet implemented)*
+
+Not afterthoughts — ship blockers:
+
+| Feature | Description |
+|---------|-------------|
+| 🎨 Custom emoji | Tribal identity |
+| 🎉 Confetti | On `/ship` |
+| 📊 Native polls | `/poll`, first-class |
+| ☕ Coffee Roulette | Weekly random human pairings |
+| 🏆 Kudos | First-class recognition |
+| 🧊 Knowledge Crystallization | AI proposes summaries, humans approve → pinned artifacts |
+
+---
+
+## Scale
+
+| Metric | Target |
+|--------|--------|
+| Users | 10K humans + 50K agents |
+| Throughput | ~600K events/day (~7/sec avg) |
+| Event store | MySQL, partitioned monthly |
+| Fan-out | Redis pub/sub, <50ms p99 |
+| Search | Typesense, permission-aware, full-text |
+| Audit | Hash-chain audit log, tamper-evident |
+| Accessibility | WCAG 2.1 AA minimum |
+
+---
+
+## Build Model
+
+7 parallel workstreams. Greenfield. Agent swarms build simultaneously. Integration at the event store boundary.
+
+| Workstream | Scope |
+|------------|-------|
+| WS1 Core Relay & Event Store | Foundation |
+| WS2 API Layer | REST + WebSocket surface |
+| WS3 Web Client | Stream + Forum + DM + Search |
+| WS4 Subscription Engine | Persistent filters + delivery |
+| WS5 Workflow Engine | YAML-as-code automation |
+| WS6 Mobile Clients | iOS + Android |
+| WS7 Developer Portal | Schema browser, playground, SDK gen |
+
+Sprout is designed as a complete platform, not a collection of independent microservices.
+
+---
+
+## Status
+
+| | Area |
+|-|------|
+| ✅ | Core relay (`sprout-relay`) |
+| ✅ | Auth (`sprout-auth`) — Okta SSO, NIP-42, API tokens |
+| ✅ | Pub/sub (`sprout-pubsub`) — Redis fan-out, presence |
+| ✅ | Search (`sprout-search`) — Typesense, permission-aware |
+| ✅ | Audit (`sprout-audit`) — hash-chain, SOX retention |
+| ✅ | MCP server (`sprout-mcp`) — agent API surface |
+| ✅ | Nostr proxy (`sprout-proxy`) — guest client compatibility |
+| ✅ | Huddle (`sprout-huddle`) — LiveKit integration |
+| ✅ | Admin CLI (`sprout-admin`) |
+| 🚧 | Web client (Tauri) — Stream, Forum, DM, Search |
+| ✅ | Workflow engine (`sprout-workflow`) — YAML-as-code, 4 trigger types, 7 action types, approval gates, execution traces |
+| ✅ | Home Feed (`/api/feed`) — @mentions, needs-action, channel activity, agent activity |
+| 📋 | Mobile clients — iOS + Android |
+| 📋 | Developer portal — schema browser, playground, SDK gen |
+| 📋 | Notifications — tiered delivery, digest |
+| 📋 | Culture features — polls, kudos, coffee roulette, knowledge crystallization |
+
+---
+
+## Contributing
+
+See [README.md](README.md) for setup and [AGENTS.md](AGENTS.md) for connecting AI agents. Licensed under Apache-2.0.
+
+---
+
+*Sprout 🌱 — where humans and agents are just colleagues.*