stack/docs/research/03-security-fleet-synthesis.md

Security Patterns, Lightweight Monitors & Final 10% Synthesis

Research Date: 2026-03-01 Repositories Analyzed:

1. tugcantopaloglu/openclaw-dashboard — Security-hardened: TOTP MFA, PBKDF2, rate limiting, memory viewer, cron manager
2. Temaki-AI/clawd-control — Lightweight fleet monitor, auto-discovery, agent creation wizard
3. spleck/claw-dashboard — Terminal-style monitor, btop-inspired
4. 23blocks-OS/ai-maestro — Agent-to-agent messaging, AMP protocol, multi-machine mesh

---

1. Memory/File Viewer (openclaw-dashboard)

How it works: Reads workspace files directly from filesystem — MEMORY.md, HEARTBEAT.md, memory/YYYY-MM-DD.md. Two API endpoints: GET /api/memory-files (list) and GET /api/memory-file?path=<path> (read content). Frontend is a simple file browser + markdown viewer. Edits create .bak backup files automatically.

Security: Path traversal protection validates all paths stay within workspace root. Read-only by default; edit requires explicit action.

Simplest implementation for Mosaic Stack:

• NestJS controller with 2 endpoints (list files, read file)
• Path validation middleware (resolve path, check it starts with workspace root)
• Next.js page: left sidebar file tree + right panel markdown render
• Use react-markdown for rendering (already likely in deps)
• Effort: 1-2h

---

2. Cron Job Management UI (openclaw-dashboard)

How it works: Reads cron jobs from $OPENCLAW_DIR/cron/jobs.json. Three endpoints:

• GET /api/crons — list all jobs with status
• POST /api/cron/:id/toggle — enable/disable
• POST /api/cron/:id/run — manually trigger

Frontend: table with Name | Schedule | Status | Last Run | Actions columns. Toggle switches and "Run Now" buttons.

For Mosaic Stack: Could be a Settings sub-tab ("Automation"). Back-end reads from DB or config file. NestJS @nestjs/schedule already supports cron — just need UI visibility into what's scheduled.

Effort: 2-3h

---

3. Agent Creation Wizard (clawd-control)

How it works: Guided multi-step form at create.html. Agent config fields:

{
  "id": "my-agent",
  "gatewayAgentId": "main",
  "name": "My Agent",
  "emoji": "🤖",
  "host": "127.0.0.1",
  "port": 18789,
  "token": "YOUR_GATEWAY_TOKEN",
  "workspace": "/path/to/agent/workspace"
}

Backend provisioning logic in create-agent.mjs. Auto-discovery via discover.mjs finds local agents automatically.

For Mosaic Stack: Already has agents table in DB. Add a "Create Agent" dialog/wizard with: name, type/model, emoji, connection details, workspace path. Multi-step or single form — single form is faster to build.

Effort: 2-4h

---

4. Fleet Overview UX (all dashboards)

What good looks like:

Dashboard	Approach	Key Insight
clawd-control	Grid of agent cards, single-screen	"See all agents at a glance with health indicators"
openclaw-dashboard	Sidebar + tabs, sparklines, heatmaps	Rich metrics: sessions, costs, rate limits
claw-dashboard	Terminal btop-style, 2s refresh	Lightweight, resource-efficient
ai-maestro	Tree view with auto-coloring	project-backend-api → 3-level tree

Key metrics that matter:

• Status indicator (online/offline/error) — most important
• Last activity timestamp
• Active session count
• Token usage / cost
• CPU/RAM (if host-level monitoring)
• Error count (last 24h)

Recommended for Mosaic Stack: Card grid layout. Each card: emoji + name, colored status dot, last activity time, token count. Click to expand/detail. Add a "Recent Activity" feed below the grid.

Effort: 3-4h

---

5. AMP Protocol (ai-maestro)

What it is: Agent Messaging Protocol — email-like communication between agents. Priority levels, message types, cryptographic signatures, push notifications. Full spec at agentmessaging.org.

Key concept: "I was the human mailman between 35 agents. AMP removes the human bottleneck."

Worth borrowing for Mosaic Stack:

• Simple agent-to-agent message table in PostgreSQL (already have DB)
• Priority levels (low/normal/high)
• Message types (task/notification/query)
• Thread awareness (threadId field)

NOT worth borrowing (yet):

• Cryptographic signatures (overkill)
• Multi-machine mesh (premature)
• Full AMP protocol compliance (too complex)

Simple alternative: Add a messages table to Prisma schema with fromAgentId, toAgentId, type, priority, subject, body, threadId, readAt. Poll or WebSocket for delivery. Effort: 4-8h

---

6. Security Patterns Worth Adopting

From openclaw-dashboard (already mature in Mosaic Stack):

Pattern	openclaw-dashboard	Mosaic Stack Status	Action
Password hashing	PBKDF2, 100k iterations	Better Auth handles this	✅ Done
CSRF protection	N/A (session-based)	Better Auth CSRF	✅ Done
RBAC	N/A	Full RBAC implemented	✅ Done
Rate limiting	5 fail → 15min lockout	Not implemented	Add NestJS throttler
TOTP MFA	Google Auth compatible	Not implemented	P2 — Better Auth plugin exists
Audit logging	All auth events logged	Not implemented	Add NestJS middleware
Security headers	HSTS, CSP, X-Frame	Partial	Add helmet middleware

Quick wins:

• @nestjs/throttler for rate limiting (30min)
• helmet middleware for security headers (15min)
• Audit log table + middleware (1-2h)

---

7. Real-Time Updates Pattern

All four dashboards use real-time updates differently:

• openclaw-dashboard: SSE (/api/live)
• clawd-control: SSE
• claw-dashboard: Polling (2s interval)
• ai-maestro: WebSocket

For Mosaic Stack: Already has WebSocket for terminal. Use SSE for fleet status (simpler than WebSocket, one-directional is fine). Polling for non-critical pages.

---

Feature Comparison Matrix

Feature	openclaw-dash	clawd-control	claw-dash	ai-maestro	Mosaic Stack
Session mgmt	✅	✅	✅	✅	✅
Memory viewer	✅	❌	❌	✅	❌
Cron mgmt	✅	❌	❌	❌	❌
Agent wizard	❌	✅	❌	✅	❌
Fleet overview	✅	✅	❌	✅	Partial
Multi-machine	❌	❌	❌	✅	❌
Agent messaging	❌	❌	❌	✅	❌
Rate limiting	✅	✅	❌	❌	❌
TOTP MFA	✅	❌	❌	❌	❌
Real-time	SSE	SSE	Poll	WS	WS (terminal)
Cost tracking	✅	❌	❌	❌	✅ (usage)
Terminal UI	❌	❌	✅	❌	✅ (xterm.js)
Kanban	❌	❌	❌	✅	✅
Auth	PBKDF2+MFA	Password	None	N/A	Better Auth
RBAC	❌	❌	❌	❌	✅