[FEATURE] Agent SDK: Secure local server mode with authentication for browser-based agents

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When developers build browser-based interfaces for Claude Code agents (whether using the Agent SDK or wrapping the CLI), the local server they create is typically exposed on localhost without authentication. This creates security risks:

1. DNS rebinding attacks: A malicious website can resolve a hostname to 127.0.0.1, bypassing same-origin restrictions to reach the local agent server
2. Local process access: Any process on the machine can connect and send commands
3. Filesystem exposure: Agent servers often expose file browsing or working directory selection endpoints
4. Arbitrary code execution: An unauthenticated caller can instruct the agent to run Bash commands

Claude Code's own interactive mode mitigates this by running in a terminal with the user directly present. But when the same capabilities are exposed over HTTP/WebSocket, the attack surface expands significantly.

Proposed Solution

If/when the Agent SDK supports an HTTP transport mode, include built-in security features:

1. Token-based authentication: Generate a random session token on startup, require it as a Bearer token or query parameter. Display it in the terminal for the user to copy. (Similar to Jupyter Notebook's token auth.)

1. Origin validation: Reject WebSocket/HTTP connections from origins other than localhost / 127.0.0.1 by default. Optionally allowlist specific origins.

1. Rate limiting: Basic rate limiting on session creation and message sending.

1. Capability scoping: Allow the server to restrict which tools, working directories, and permission modes are available to HTTP clients, independent of what the underlying agent supports.

1. Audit logging: Log all session creation, tool approvals, and commands to a file for post-hoc review.

Alternative Solutions

• Documentation-only approach: Publish a "security considerations for agent servers" guide. Lower effort but relies on developers implementing correctly.
• Middleware library: Provide authentication/origin-checking middleware that developers add to their own servers. More flexible but more work per integration.
• Leave to developers: Status quo. Developers figure out security on their own, with predictable results.

Priority

• [ ] Critical - Blocking my work
• [ ] High - Significant impact on productivity
• [ ] Medium - Would be very helpful
• [x] Low - Nice to have

Feature Category

• [ ] CLI commands and flags
• [ ] Interactive mode (TUI)
• [ ] File operations
• [ ] API and model interactions
• [ ] MCP server integration
• [ ] Performance and speed
• [ ] Configuration and settings
• [x] Developer tools/SDK
• [ ] Documentation
• [ ] Other

Use Case Example

A developer runs npx create-claude-agent-server (hypothetical) which starts a local agent server on port 3456. On startup, the server:

1. Generates a random token: Agent server running at http://localhost:3456?token=abc123def
2. Rejects connections without the token
3. Validates that the Origin header is http://localhost:3456
4. Logs all operations to ~/.claude/agent-server.log

This matches the Jupyter Notebook security model, which has been battle-tested for the same use case (local server accessed via browser).

Additional Context

This is a forward-looking request that only becomes relevant if the Agent SDK adds HTTP/WebSocket transport (see related feature request for HTTP transport). However, security should be designed into the transport from the start rather than bolted on later.

The existing third-party project The Vibe Companion exposes an unauthenticated HTTP server with filesystem browsing, session creation with arbitrary binary paths, and agent control -- all accessible to any process on the machine. This demonstrates the risk when security isn't part of the transport layer.