Ops & Security

Quick start (prod-ready)

1. Run the Hub behind a reverse proxy with TLS (e.g., NGINX, Traefik).
2. Set strict CORS and Private Network Access headers.
3. Enable control-plane APIs only when needed and guard with tokens.
4. Expose /metrics to your monitoring stack; add alerts for queues and uptime.

CORS & Private Network Access (PNA)

The Hub sets CORS and PNA headers via an after_request hook. Configure allow-lists using environment variables:

• AETHERRA_CORS_ALLOW_PATTERN: Regex for allowed origins (e.g., ^https://(www\\.)?aetherra\\.dev$).
• AETHERRA_PNA_ALLOW: Set to 1 to send Access-Control-Allow-Private-Network: true on preflights.

Symptoms and fixes:

• PNA blocked: ensure the response to the preflight OPTIONS request includes Access-Control-Allow-Private-Network: true and that your proxy preserves it.
• Preflight 404/405: the Hub responds to global OPTIONS /<any>. If you still see 404s, your proxy may be intercepting or stripping headers; add a pass-through rule.

Authentication & control plane

Control endpoints are opt-in and token-guarded:

• AETHERRA_HUB_CONTROL_ENABLED=1 — enable kernel control endpoints.
• AETHERRA_HUB_CONTROL_TOKEN=<secret> — clients send X-Aetherra-Token.

Optional AI/Agents APIs have corresponding toggles and tokens:

• AETHERRA_AI_API_ENABLED, AETHERRA_AI_API_TOKEN, AETHERRA_AI_API_REQUIRE_TOKEN
• AETHERRA_AGENTS_API_ENABLED, AETHERRA_AGENTS_API_TOKEN, AETHERRA_AGENTS_API_REQUIRE_TOKEN

Reverse proxy example (NGINX)

server {
  listen 443 ssl;
  server_name hub.example.com;

  # TLS config...

  location / {
    proxy_pass http://127.0.0.1:3001;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto https;
    # Preserve CORS/PNA headers from the Hub
    proxy_pass_header Access-Control-Allow-Origin;
    proxy_pass_header Access-Control-Allow-Headers;
    proxy_pass_header Access-Control-Allow-Methods;
    proxy_pass_header Access-Control-Allow-Credentials;
    proxy_pass_header Access-Control-Allow-Private-Network;
  }
}

Endpoints to expose

• /api/site_status (or /site_status) — small JSON for dashboards/widgets.
• /metrics — Prometheus text; includes queue sizes and uptime.
• /api/tasks/:id/stream — optional SSE-like stream for task logs (guarded by token if configured).

Hardening checklist

• Run Hub as a non-root user; lock down file permissions.
• Restrict CORS origins with AETHERRA_CORS_ALLOW_PATTERN; avoid * in production.
• Rotate control tokens and keep them out of logs; prefer header auth.
• Rate-limit public endpoints at the proxy layer; set body size limits.
• Isolate plugins with least privilege; disable unused capabilities.

Troubleshooting

• Docs widget spams /api/site_status 404: the frontend will try once and cache-disable for the session; upgrade the Hub or expose the alias /site_status.
• Cross-origin auth fails: ensure your proxy allows X-Aetherra-Token in Access-Control-Allow-Headers.
• Metrics missing: confirm /metrics is reachable and not blocked by auth; scrape interval ≥ 15s recommended.