Nerve is designed as a local-first web UI for an AI agent. Its security model assumes the server runs on a trusted machine and is accessed by its owner. It is not designed for multi-tenant or public-internet deployment without an additional reverse proxy and authentication layer.

• Threat Model
• Authentication & Access Control
• CORS Policy
• Security Headers
• Rate Limiting
• Input Validation
• File Serving Security
• WebSocket Proxy Security
• Body Size Limits
• Path Traversal Prevention
• TLS / HTTPS
• Token & Secret Handling
• Client-Side Security
• Configuration File Security
• Reporting Vulnerabilities

• Multi-user authentication — Nerve supports single-user password authentication. Multi-user accounts with roles are not yet implemented.
• End-to-end encryption — TLS covers transport; at-rest encryption of memory files or session data is not provided.
• DDoS protection — The in-memory rate limiter handles casual abuse but is not designed for sustained attacks. Use a reverse proxy (nginx, Cloudflare) for production exposure.

Nerve includes a built-in session-cookie-based authentication layer that can be enabled via the NERVE_AUTH environment variable.

Security is enforced through network-level controls:

1. Localhost binding — The server binds to 127.0.0.1 by default. Only local processes can connect.
2. CORS allowlist — Browsers enforce the Origin check. Only configured origins receive CORS headers.
3. Gateway token isolation — The sensitive GATEWAY_TOKEN is never sent to the browser. Instead, Nerve injects it server-side into the WebSocket connection upgrade for trusted clients.
4. Client config persistence — The frontend stores the gateway URL and optional manual token in localStorage as oc-config. Trusted official-gateway flows usually keep the token empty because server-side injection handles auth.

All API endpoints (except /api/auth/* and /health) require a valid session cookie. WebSocket upgrade requests are also checked.

How it works:

1. User submits a password via POST /api/auth/login
2. The server verifies the password against a stored scrypt hash (or accepts the gateway token as a fallback)
3. On success, a signed HttpOnly session cookie is set
4. All subsequent requests include the cookie automatically
5. The session token is a stateless HMAC-SHA256 signed payload containing only an expiry timestamp

Session cookie security:

Password storage:

• Passwords are hashed with scrypt (32-byte random salt, 64-byte derived key)
• Timing-safe comparison prevents timing attacks
• Passwords are never stored in plaintext or logged

Gateway token fallback:

Users who haven't set a dedicated password can authenticate using their existing GATEWAY_TOKEN. This provides zero-config authentication when upgrading to network access.

When exposing Nerve to a network (HOST=0.0.0.0):

• Enable authentication — the setup wizard prompts for this automatically
• Using a VPN (Tailscale, WireGuard) adds an additional layer of security
• Placing Nerve behind a reverse proxy with HTTPS is recommended for production
• The gateway token can serve as an immediate fallback password

CORS is enforced on all requests via Hono's CORS middleware.

Default allowed origins (auto-configured):

• http://localhost:{PORT}
• https://localhost:{SSL_PORT}
• http://127.0.0.1:{PORT}
• https://127.0.0.1:{SSL_PORT}

Additional origins via ALLOWED_ORIGINS env var (comma-separated). Each entry is normalised through the URL constructor:

ALLOWED_ORIGINS=http://100.64.0.5:3080,https://my-server.tailnet.ts.net:3443

Allowed methods: GET, POST, PUT, DELETE, OPTIONS
Allowed headers: Content-Type, Authorization
Credentials: Enabled (credentials: true)

Requests with no Origin header (same-origin, non-browser) are allowed through.

Applied to every response via the securityHeaders middleware:

Implementation note: CSP directives are built lazily on first request (not at module import time) to avoid race conditions with dotenv/config load order. The computed directives are then cached for the lifetime of the process.

default-src 'self';
script-src 'self' https://s3.tradingview.com;
style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;
font-src 'self' https://fonts.gstatic.com;
connect-src 'self' ws://localhost:* wss://localhost:* http://localhost:* https://localhost:*
            ws://127.0.0.1:* wss://127.0.0.1:* http://127.0.0.1:* https://127.0.0.1:*
            [CSP_CONNECT_EXTRA];
img-src 'self' data: blob:;
media-src 'self' blob:;
frame-src https://s3.tradingview.com https://www.tradingview.com
          https://www.tradingview-widget.com https://s.tradingview.com;
frame-ancestors 'none';
base-uri 'self';
form-action 'self'

TradingView domains: The script-src and frame-src entries for TradingView are required for the inline tv chart type, which uses TradingView's official widget embed script. The script injects iframes from multiple TradingView subdomains.

The connect-src directive can be extended via CSP_CONNECT_EXTRA (space-separated). Input is sanitised:

• Semicolons (;) and newlines (\r, \n) are stripped to prevent directive injection
• Only entries matching http://, https://, ws://, or wss:// schemes are accepted

In-memory sliding window rate limiter applied to all /api/* routes.

• Per-client, per-path — Each unique clientIP:path combination gets its own sliding window.
• Client identification — Uses the real TCP socket address from getConnInfo(). Not spoofable via request headers.
• Trusted proxies — X-Forwarded-For and X-Real-IP are only honoured when the direct connection comes from an IP in TRUSTED_PROXIES (default: loopback addresses only). Extend via TRUSTED_PROXIES env var.
• Store cap — The rate limit store is capped at 10,000 entries to prevent memory amplification from spoofed IPs (when behind a trusted proxy). When full, the oldest entry is evicted.
• Cleanup — Expired timestamps are purged every 5 minutes.

Every response includes:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57

When rate-limited (HTTP 429):

Retry-After: 42
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708100060

All POST/PUT endpoints validate request bodies with Zod schemas:

Validation errors return HTTP 400 with the first Zod issue message as plain text or JSON.

The GET /api/files endpoint serves local image files with multiple layers of protection:

Only image files are served:

Non-image file types return 403 Not an allowed file type.

Files are only served from these directories:

The request path is resolved to an absolute path via path.resolve(), blocking .. traversal. The resolved path must start with one of the allowed prefixes (with a path separator check to prevent /tmp-evil matching /tmp).

After the prefix check passes, the file's real path is resolved via fs.realpathSync(). The real path is then re-checked against the same prefix allowlist. This prevents:

• Symlinks inside /tmp pointing to /etc/passwd
• Symlinks inside ~/.openclaw pointing outside the allowed tree

If the real path falls outside allowed prefixes → 403 Access denied.

The ~ prefix in input paths is expanded to os.homedir() before resolution, preventing home directory confusion.

The WebSocket proxy (connecting the frontend to the OpenClaw gateway) restricts target hostnames:

Default allowed hosts: localhost, 127.0.0.1, ::1

Extend via WS_ALLOWED_HOSTS env var (comma-separated):

WS_ALLOWED_HOSTS=my-server.tailnet.ts.net,100.64.0.5

This prevents the proxy from being used to connect to arbitrary external hosts.

Nerve performs server-side token injection to provide a zero-config connection experience for local and authenticated users without exposing the GATEWAY_TOKEN to the browser storage.

Injection Logic:

1. GET /api/connect-defaults returns the official gateway WebSocket URL, token: null, and a serverSideAuth flag.
2. The WebSocket proxy only injects GATEWAY_TOKEN when all of these are true:
   • a gateway token is configured on the server
   • the request is trusted (loopback access or an authenticated session)
   • the WebSocket upgrade Origin is allowed
3. For the official gateway URL, the browser connects with an empty token when serverSideAuth=true.
4. Custom gateway URLs or untrusted contexts still require manual token entry in the connect dialog.

This keeps the managed gateway token on the server while still allowing explicit manual credentials for unsupported or custom connection paths.

OpenClaw 2026.2.19+ requires a signed device identity (Ed25519 keypair) for WebSocket connections to receive operator.read / operator.write scopes. Plain token authentication alone grants zero scopes.

Nerve generates a persistent device identity on first start (stored at ~/.nerve/device-identity.json) and injects it into the connect handshake. The gateway always stays on loopback (127.0.0.1) — Nerve proxies all external connections through its WS proxy.

First-time pairing (required once):

1. Start Nerve and open the UI in a browser
2. The first connection creates a pending pairing request on the gateway
3. Approve it: openclaw devices list → openclaw devices approve <requestId>
4. All subsequent connections are automatically authenticated

If the device is rejected (e.g. after a gateway reset), the proxy falls back to token-only auth. The connection succeeds but with reduced scopes — chat and tool calls may fail with "missing scope" errors. Re-approve the device to restore full functionality.

Architecture: Browser (remote) → Nerve (0.0.0.0:3080) → WS proxy → Gateway (127.0.0.1:18789). The gateway never needs to bind to LAN or be directly network-accessible.

Exceeding the global body limit returns 413 Request body too large.

Multiple layers prevent directory traversal attacks:

Nerve automatically starts an HTTPS server alongside HTTP when certificates are present:

certs/cert.pem    # X.509 certificate
certs/key.pem     # RSA/EC private key

HSTS is always sent (max-age=31536000; includeSubDomains), even over HTTP. Browsers that have previously visited over HTTPS will refuse HTTP connections for 1 year.

Microphone access requires a secure context. On localhost HTTP works, but network access requires HTTPS.

The setup wizard applies chmod 600 to .env and backup files, restricting read access to the file owner.

The setup wizard:

1. Writes .env atomically (via temp file + rename)
2. Applies chmod 600 to .env and backup files
3. Cleans up .env.tmp on interruption (Ctrl+C handler)
4. Backs up existing .env before overwriting (timestamped .env.bak.*)

If you find a security issue, please open a GitHub issue or contact the maintainers directly. Do not disclose vulnerabilities publicly before they are addressed.