Flow Mesh Security Model

Authentication

Multi-User Password Auth

  • Passwords stored as bcrypt hashes (cost 12) in SQLite kv table
  • Key format: auth_user:<username> → bcrypt hash
  • Users created via first-run wizard or FLOW_MESH_USER/FLOW_MESH_PASS env 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_TOKEN env 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 _csrf field in all HTML forms
  • Validated: On POST/PUT/DELETE to non-API, non-webhook, non-login paths
  • Header fallback: X-CSRF-Token header 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 Requests with Retry-After: 60 header
  • 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-Secret header 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-wal files (safe with WAL mode)
  • Auth credentials (bcrypt hashes) in kv table — 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 a 0600 config.yaml (coding_api_key is config-only)
  • Fallback: DB intelligence_config table (set via Setup UI)
  • Resolution order: env var → DB → empty
  • Keys never stored in config.yaml or 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 pi in headless mode with restricted permissions
  • Delegation policy modes: auto (immediate), ask (approval required), never (suggest only)
  • All delegations logged in intelligence_delegations table with full audit trail

Generated from the Flow Mesh repository by scripts/build-docs-site.sh. If a page is wrong here, the file it was rendered from is wrong.