Skip to content

feat: add backend proxy layer to keep auth tokens server-side#1

Merged
mrgoonie merged 3 commits intomainfrom
claude/silly-wilbur
Mar 22, 2026
Merged

feat: add backend proxy layer to keep auth tokens server-side#1
mrgoonie merged 3 commits intomainfrom
claude/silly-wilbur

Conversation

@mrgoonie
Copy link
Copy Markdown
Contributor

Overview

Adds an optional backend proxy server that allows keeping GoClaw authentication tokens server-side, improving security for production deployments.

Changes

New Proxy Server (server/)

  • proxy-server.ts: HTTP + WebSocket server with origin validation, per-IP connection limits, and graceful shutdown
  • websocket-proxy-session.ts: Handles individual client connections, intercepts connect frames to inject auth tokens server-side
  • connection-tracker.ts: Per-IP rate limiting to prevent abuse
  • proxy-config.ts: Environment variable configuration with sensible defaults
  • package.json: Node.js server with ws as sole production dependency
  • .env.example: Configuration template for deployment

Widget Updates

  • Updated src/types.ts to support new proxyUrl configuration option
  • Modified src/websocket-client.ts to connect via proxy when configured
  • Token is now optional when using proxy mode

Documentation & Examples

  • Updated CLAUDE.md, README.md, code-standards.md with proxy server details
  • Updated system-architecture.md with dual-mode security model
  • Added examples/proxy-mode.html demonstrating secure deployment pattern
  • Updated project-overview-pdr.md with proxy architecture

Security Benefits

  • Token never exposed to client: Proxy holds credentials server-side
  • Origin validation: Restrict connections by domain
  • Rate limiting: Per-IP connection limits prevent abuse
  • Reverse proxy support: TRUST_PROXY flag for nginx/Cloudflare deployments

Deployment

cd server && npm install
cp .env.example .env  # Configure GOCLAW_URL and GOCLAW_TOKEN
npm run dev           # Development
npm run build && npm start  # Production

Architecture

Browser Widget → Proxy Server (:3100) → GoClaw Gateway (:9090)
  (no token)      (holds token)          (validates token)

Introduces a WebSocket proxy server (server/) that sits between the
webchat widget and GoClaw Gateway, preventing auth token exposure in
client-side JavaScript.

- Proxy intercepts WS connect frame and injects gateway token
- Widget updated with proxyUrl config option for proxy mode
- Origin validation, per-IP rate limiting, TRUST_PROXY support
- 512KB max frame size, message buffering, graceful shutdown
- Example page and documentation updated
…ken leakage

- Reject missing Origin header when allowedOrigins is configured
- Cap pending message buffer to 10 messages (prevents memory DoS)
- Add per-session message rate limiting (60 msgs/min sliding window)
- Sanitize upstream responses to strip token fields (defense in depth)
…nt-side auth

Removes direct mode entirely — the webchat widget now connects exclusively through the backend proxy, which keeps the gateway auth token server-side. Client never receives or sends the token.

Changes:
- Config: removed `token` and `proxyUrl` fields; renamed `proxyUrl` → `url` (required), `proxyApiKey` → `apiKey` (optional).
- Client: removed token sending logic; proxy injects token at connection time.
- Server: added optional API key validation for proxy endpoints.
- Docs: rewrote README for proxy-only setup, removed direct mode examples.

This hardens security by eliminating token exposure in client-side code and browser storage.
@mrgoonie mrgoonie merged commit 74abe6b into main Mar 22, 2026
1 check passed
@mrgoonie mrgoonie deleted the claude/silly-wilbur branch March 27, 2026 06:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant