Flow Mesh Security Model
Authentication
Multi-User Password Auth
- Passwords stored as bcrypt hashes (cost 12) in SQLite
kvtable - Key format:
auth_user:<username>→ bcrypt hash - Users created via first-run wizard or
FLOW_MESH_USER/FLOW_MESH_PASSenv vars - Env vars upsert into DB on every startup (bootstrap/reset mechanism)
Session Cookies
| Property | Value |
|---|---|
| Cookie name | fm_session |
| Format | username|timestamp|HMAC-SHA256-signature |
| Signing key | 32-byte random, stored in DB (kv.auth_hmac_secret) |
| Algorithm | HMAC-SHA256 |
| TTL | 7 days (remember me) or 1 day |
| Flags | HttpOnly, SameSite=Lax, Path=/ |
| Revocation | Clear cookie via /logout; rotate signing key to invalidate all sessions |
Stateless validation: Server recomputes HMAC from username|timestamp + secret key. No session table, no server-side state. Survives restarts (key persists in DB).
Smart Activation
Auth is automatically determined by listen address unless overridden:
| Condition | Auth Active |
|---|---|
FLOW_MESH_AUTH=on |
Yes (override) |
FLOW_MESH_AUTH=off |
No (override) |
Listen 127.0.0.1:* |
No (loopback safe) |
Listen localhost:* |
No (loopback safe) |
Listen 0.0.0.0:* |
Yes (network exposed) |
Note: Behind a reverse proxy or CF tunnel, the app still listens on loopback. Use FLOW_MESH_AUTH=on explicitly.
API Token Auth
Optional bearer token for API endpoints (CLI/agent access):
Authorization: Bearer <FLOW_MESH_API_TOKEN>
- Set via
FLOW_MESH_API_TOKENenv var only (not in config) - Gates
/api/*paths except/api/health - Bypasses session auth (useful for headless agents)
CSRF Protection
- Token-based: Random 16-byte hex tokens, single-use, 1-hour expiry
- Injected: Hidden
_csrffield in all HTML forms - Validated: On POST/PUT/DELETE to non-API, non-webhook, non-login paths
- Header fallback:
X-CSRF-Tokenheader accepted - Exempt:
/api/*(uses bearer token),/webhooks/*(uses own auth),/login(pre-auth)
Rate Limiting
- Per-IP sliding window: 120 requests per minute
- IP extraction:
X-Forwarded-For→X-Real-IP→RemoteAddr - Response:
429 Too Many RequestswithRetry-After: 60header - Cleanup: Stale IP entries pruned every 5 minutes
Input Sanitization
Display Names
- Trimmed whitespace
- Control characters stripped (keeps printable + space)
- Max 255 characters
Request Bodies
- 2MB max (enforced via
http.MaxBytesReader)
Database Errors
- Raw SQL errors never exposed to client
- Generic messages returned: "duplicate entry", "invalid value", "required field missing"
- Reference IDs logged for debugging
Webhook Security
Asana Webhooks
- Handshake: Asana sends
X-Hook-Secretheader on setup; server echoes it back - Verification: Subsequent events include
X-Hook-Signature(HMAC-SHA256 of body) - Path:
/webhooks/asana— exempt from session auth and CSRF
Secrets Management
| Secret | Storage | Notes |
|---|---|---|
| Asana PAT | Env var FLOW_MESH_ASANA_PAT |
Never in config.yaml |
| Discord bot token | Env var FLOW_MESH_DISCORD_TOKEN |
Never in config.yaml |
| OAuth client secrets | Env vars | Never in config.yaml |
| User passwords | bcrypt hashes in SQLite | Never stored plaintext |
| Session signing key | SQLite kv table |
Auto-generated, hex-encoded |
| API token | Env var FLOW_MESH_API_TOKEN |
Never in config.yaml |
Rule: Secrets are either env vars or derived/generated in the DB. The config.yaml file and git repo should never contain credentials.
Network Security
- Default listen:
127.0.0.1:8300— loopback only, not network-accessible - Exposure: Via reverse proxy (nginx/Caddy) or Cloudflare Tunnel
- TLS: Terminated at the proxy/tunnel layer, not by Flow Mesh itself
- CORS: Not configured (same-origin only, htmx UI)
Data at Rest
- SQLite database is unencrypted on disk
- Protect via filesystem permissions (
chmod 600) - Backup strategy: copy
.db+.db-walfiles (safe with WAL mode) - Auth credentials (bcrypt hashes) in
kvtable — no plaintext passwords stored
Threat Model
| Threat | Mitigation |
|---|---|
| Brute force login | Rate limiting (120/min per IP) |
| Session hijacking | HttpOnly + SameSite cookies, HMAC validation |
| CSRF | Per-request tokens, single-use |
| SQL injection | Parameterized queries throughout |
| XSS | Go html/template auto-escaping |
| Request flooding | Body size limit (2MB), rate limiter |
| Credential theft from config | Secrets in env vars only, never in files |
| Webhook spoofing | HMAC signature verification (Asana) |
| Stale sessions | 7-day max TTL, rotate signing key to mass-invalidate |
Intelligence Layer Security
API Key Storage
- Preferred: Environment variables (
FLOW_MESH_INTELLIGENCE_API_KEY) or a0600config.yaml(coding_api_keyis config-only) - Fallback: DB
intelligence_configtable (set via Setup UI) - Resolution order: env var → DB → empty
- Keys never stored in
config.yamlor git
Data Privacy
- Conversation content (including tool outputs with task data) is sent to the configured LLM provider
- For complete data privacy, use a local model via Ollama (
chat_provider=ollama) - Conversation history persisted in
intelligence/channels/directory (local disk only)
Prompt Injection Defense
- User input sanitized via 11 regex patterns (
SanitizeInput()) - Tool outputs (task titles, descriptions) are NOT sanitized — the system prompt instructs the LLM to only follow user messages, not data content
- This is a known limitation of all LLM-based systems (indirect prompt injection)
Rate Limiting
- Per-channel: 20 messages/minute, 200 messages/hour
- Max 3 concurrent delegations, 5-minute timeout per delegation
- Daily spending limit (configurable, default $5.00)
Delegation Security
- Coding delegations run
piin headless mode with restricted permissions - Delegation policy modes:
auto(immediate),ask(approval required),never(suggest only) - All delegations logged in
intelligence_delegationstable with full audit trail