Security Best Practices

Mission Control implements multiple layers of security to protect sensitive agent orchestration data, API keys, and user credentials. This guide covers authentication methods, role-based access control (RBAC), network security, and deployment best practices.

Authentication

Mission Control supports multiple authentication methods:

Session-Based Authentication

The primary authentication method uses secure HTTP-only cookies with cryptographically random session tokens. Login flow:

User submits credentials to /api/auth/login
Server validates credentials using constant-time comparison (timing attack prevention)
On success, creates session token (32-byte random hex) with 7-day expiration
Returns mc-session cookie with httpOnly, secure (in production), and sameSite=strict flags
Subsequent requests include session cookie for authentication

Session security features (src/lib/auth.ts:104-121):

const SESSION_DURATION = 7 * 24 * 60 * 60 // 7 days
const token = randomBytes(32).toString('hex')

Cryptographic randomness: Uses Node.js crypto.randomBytes(32) for unpredictable tokens
Automatic expiration: Sessions expire after 7 days
Cleanup: Expired sessions are purged on new session creation
IP & User-Agent tracking: Sessions log IP address and user agent for audit trails

API Key Authentication

For headless/programmatic access, use API key authentication:

curl -H "x-api-key: your-api-key" https://mc.example.com/api/...

Security implementation (src/proxy.ts:100-106):

const apiKey = request.headers.get('x-api-key')
if (apiKey && safeCompare(apiKey, process.env.API_KEY || '')) {
  return applySecurityHeaders(NextResponse.next())
}

Constant-time comparison: Uses crypto.timingSafeEqual() to prevent timing attacks
Admin privileges: API key grants full admin access (synthetic user with role: 'admin')
Single key: One API key per instance (rotate regularly)

Generate a strong API key with high entropy:

openssl rand -hex 32

Never commit API_KEY to version control.

Google OAuth (Optional)

Mission Control supports Google Sign-In with approval workflow:

User clicks “Sign in with Google”
Google OAuth flow validates user identity
Admin approval required: New Google users are created with is_approved=0
Admin approves user via UI or API
User can then access the dashboard

Configuration:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
NEXT_PUBLIC_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com

Create OAuth credentials in Google Cloud Console and configure authorized origins/redirect URIs.

Role-Based Access Control (RBAC)

Mission Control implements a three-tier role hierarchy:

Role	Level	Permissions
viewer	0	Read-only access to dashboards, logs, and metrics
operator	1	Viewer permissions + trigger pipelines, manage agents, modify configurations
admin	2	Operator permissions + user management, system settings, API key access

Role enforcement (src/lib/auth.ts:300-319):

const ROLE_LEVELS: Record<string, number> = { viewer: 0, operator: 1, admin: 2 }

export function requireRole(
  request: Request,
  minRole: User['role']
): { user: User } | { error: string; status: 401 | 403 } {
  const user = getUserFromRequest(request)
  if (!user) {
    return { error: 'Authentication required', status: 401 }
  }
  if ((ROLE_LEVELS[user.role] ?? -1) < ROLE_LEVELS[minRole]) {
    return { error: `Requires ${minRole} role or higher`, status: 403 }
  }
  return { user }
}

API routes use requireRole() to enforce minimum role requirements:

// Example: /api/users (admin only)
const auth = requireRole(request, 'admin')
if ('error' in auth) {
  return NextResponse.json({ error: auth.error }, { status: auth.status })
}
const user = auth.user

Managing Users

Admins can manage users via the UI or API:

curl -X POST https://mc.example.com/api/users \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "operator1",
    "password": "strong-password-min-12-chars",
    "display_name": "Operator One",
    "role": "operator"
  }'

Password minimum length: 12 characters (enforced in src/lib/auth.ts:208)

Network Access Control

Mission Control implements default-deny host-based access control in production environments.

How It Works (src/proxy.ts:56-70)

const hostName = getRequestHostname(request) // From x-forwarded-host or host header
const allowAnyHost = envFlag('MC_ALLOW_ANY_HOST') || process.env.NODE_ENV !== 'production'
const allowedPatterns = String(process.env.MC_ALLOWED_HOSTS || '')
  .split(',')
  .map((s) => s.trim())
  .filter(Boolean)

const isAllowedHost = allowAnyHost || allowedPatterns.some((p) => hostMatches(p, hostName))

if (!isAllowedHost) {
  return new NextResponse('Forbidden', { status: 403 })
}

Behavior:

Development (NODE_ENV !== 'production'): All hosts allowed by default
Production (NODE_ENV === 'production'): Only hosts matching MC_ALLOWED_HOSTS patterns are allowed
Override: Set MC_ALLOW_ANY_HOST=true to disable (not recommended in production)

Allowed Host Patterns

Supports flexible pattern matching (src/proxy.ts:28-46):

Pattern	Example	Matches	Does NOT Match
Exact host	`app.example.com`	`app.example.com`	`api.example.com`, `app.example.com:8080`
Subdomain wildcard	`*.example.com`	`api.example.com`, `app.example.com`	`example.com` (bare domain)
Prefix wildcard	`100.*`	`100.64.0.1`, `100.100.100.100`	`10.0.0.1`

Example configuration:

MC_ALLOWED_HOSTS=localhost,127.0.0.1,mc.example.com,*.internal.example.com,100.*

This allows:

localhost and 127.0.0.1 (local development/testing)
mc.example.com (production domain)
api.internal.example.com, dashboard.internal.example.com (internal subdomains)
100.64.0.1, 100.100.100.100 (Tailscale IP range)

Always configure MC_ALLOWED_HOSTS in production to prevent unauthorized access from spoofed Host headers.Never set MC_ALLOW_ANY_HOST=true in production unless absolutely necessary.

CSRF Protection

Mission Control validates the Origin header for state-changing requests (src/proxy.ts:74-88):

const method = request.method.toUpperCase()
if (['POST', 'PUT', 'DELETE', 'PATCH'].includes(method)) {
  const origin = request.headers.get('origin')
  if (origin) {
    const originHost = new URL(origin).host
    const requestHost = request.headers.get('host')?.split(',')[0]?.trim()
    if (originHost && requestHost && originHost !== requestHost) {
      return NextResponse.json({ error: 'CSRF origin mismatch' }, { status: 403 })
    }
  }
}

Protection:

Validates Origin header matches Host header for POST/PUT/DELETE/PATCH requests
Prevents cross-site request forgery attacks
Works automatically with modern browsers

Security Headers

All responses include security headers (src/proxy.ts:48-53):

function applySecurityHeaders(response: NextResponse): NextResponse {
  response.headers.set('X-Content-Type-Options', 'nosniff')
  response.headers.set('X-Frame-Options', 'DENY')
  response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin')
  return response
}

Header	Value	Purpose
`X-Content-Type-Options`	`nosniff`	Prevent MIME type sniffing attacks
`X-Frame-Options`	`DENY`	Prevent clickjacking (no iframe embedding)
`Referrer-Policy`	`strict-origin-when-cross-origin`	Limit referrer information leakage

Recommended reverse proxy headers (add via Nginx/Caddy):

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';" always;

TLS / HTTPS

Always deploy Mission Control behind a reverse proxy with TLS in production.Never expose the Node.js server directly to the internet.

Enable Secure Cookies

When serving over HTTPS, enable secure cookies:

MC_COOKIE_SECURE=true

This sets the Secure flag on session cookies, preventing transmission over unencrypted HTTP. Default behavior:

Production (NODE_ENV=production): secure=true unless explicitly set to false
Development: secure=false (allows testing over HTTP)

Reverse Proxy TLS Termination

See Production Deployment - Reverse Proxy Configuration for Nginx/Caddy/Traefik examples with:

TLS 1.2/1.3 only
Strong cipher suites
HSTS (Strict-Transport-Security)
HTTP to HTTPS redirect

Password Security

Mission Control uses industry-standard password hashing:

Algorithm: Argon2id (via @node-rs/argon2 or fallback to bcrypt)
Verification: Constant-time comparison to prevent timing attacks
Minimum length: 12 characters (enforced at user creation)

Password with special characters: If AUTH_PASS contains #, use one of these methods:

# Method 1: Quote the value
AUTH_PASS="my#password"

# Method 2: Base64 encoding
AUTH_PASS_B64=$(echo -n 'my#password' | base64)

Secrets Management

Never commit .env files to version control.The repository .gitignore already excludes these files:

.env
.env.local
.env.production

Best Practices

Use environment-specific files:
- Development: .env.local
- Production: .env or secret management service

Rotate credentials regularly:

# Generate new API key
openssl rand -hex 32

# Update AUTH_PASS for admin
openssl rand -base64 32

Use secret management services:
- Docker Swarm: Docker Secrets
- Kubernetes: Sealed Secrets or External Secrets Operator
- Cloud: AWS Secrets Manager, Azure Key Vault, Google Secret Manager

Restrict file permissions:

chmod 600 /opt/mission-control/.env
chown mission-control:mission-control /opt/mission-control/.env

1Password Integration

Mission Control supports pulling secrets from 1Password CLI:

OP_VAULT_NAME=production

The Integrations panel can fetch secrets from the specified vault.

Gateway Security

Device Identity & WebCrypto

Mission Control uses WebCrypto for device identity signing when connecting to gateways:

Device identity requires a secure context (HTTPS or localhost).If you see “Gateway error: device identity required”, ensure Mission Control is served over HTTPS.

Gateway Origin Allowlist

Configure your OpenClaw gateway to allow Mission Control origins:

openclaw.json

{
  "gateway": {
    "controlUi": {
      "allowedOrigins": ["https://mc.example.com"]
    }
  }
}

Restart the gateway after updating the configuration.

Audit Logging

Mission Control logs security-relevant events:

User authentication: Login attempts, session creation/destruction
User management: User creation, role changes, deletions
API access: API key usage with IP address and user agent
Configuration changes: System settings modifications

Retention:

MC_RETAIN_AUDIT_DAYS=365  # Keep audit logs for 1 year

See Environment Variables - Data Retention.

Security Checklist

Reporting Vulnerabilities

If you discover a security vulnerability in Mission Control:

Do not open a public issue.Email security@builderz.dev with:

Description of the vulnerability
Steps to reproduce
Potential impact
Suggested fix (if any)

We will acknowledge receipt within 48 hours and aim to provide a fix within 7 days for critical issues.

Additional Resources

Environment Variables - Complete configuration reference
Docker Deployment - Container security best practices
Production Deployment - Infrastructure hardening

Get Started

Core Features

Integrations

Deployment

Advanced

Authentication

Session-Based Authentication

API Key Authentication

Google OAuth (Optional)

Role-Based Access Control (RBAC)

Managing Users

Network Access Control

How It Works (src/proxy.ts:56-70)

Allowed Host Patterns

CSRF Protection

Security Headers

TLS / HTTPS

Enable Secure Cookies

Reverse Proxy TLS Termination

Password Security

Secrets Management

Best Practices

1Password Integration

Gateway Security

Device Identity & WebCrypto

Gateway Origin Allowlist

Audit Logging

Security Checklist

Reporting Vulnerabilities

Additional Resources

Build docs developers (and LLMs) love

Get Started

Core Features

Integrations

Deployment

Advanced

Documentation Index

​Authentication

​Session-Based Authentication

​API Key Authentication

​Google OAuth (Optional)

​Role-Based Access Control (RBAC)

​Managing Users

​Network Access Control

​How It Works (src/proxy.ts:56-70)

​Allowed Host Patterns

​CSRF Protection

​Security Headers

​TLS / HTTPS

​Enable Secure Cookies

​Reverse Proxy TLS Termination

​Password Security

​Secrets Management

​Best Practices

​1Password Integration

​Gateway Security

​Device Identity & WebCrypto

​Gateway Origin Allowlist

​Audit Logging

​Security Checklist

​Reporting Vulnerabilities

​Additional Resources

Build docs developers (and LLMs) love

Authentication

Session-Based Authentication

API Key Authentication

Google OAuth (Optional)

Role-Based Access Control (RBAC)

Managing Users

Network Access Control

How It Works (src/proxy.ts:56-70)

Allowed Host Patterns

CSRF Protection

Security Headers

TLS / HTTPS

Enable Secure Cookies

Reverse Proxy TLS Termination

Password Security

Secrets Management

Best Practices

1Password Integration

Gateway Security

Device Identity & WebCrypto

Gateway Origin Allowlist

Audit Logging

Security Checklist

Reporting Vulnerabilities

Additional Resources