feat: Add optional authentication for web viewer when exposed to network

[github-actions[bot]]

Originally posted as issue #266 by @informatJonas
#266

Summary

When CLAUDE_MEM_WORKER_HOST is set to 0.0.0.0, the web viewer becomes accessible to anyone on the network without any authentication. This exposes sensitive data including:

• Session observations and learnings
• User prompts
• Project structure information
• Timeline of all coding activities

Proposed Solution

Add optional authentication when the viewer is exposed beyond localhost:

Option 1: Token-based Auth (Recommended)

{
  "CLAUDE_MEM_WORKER_HOST": "0.0.0.0",
  "CLAUDE_MEM_AUTH_ENABLED": "true",
  "CLAUDE_MEM_AUTH_TOKEN": "auto"  // or user-defined token
}

• auto generates a random token on first start, stored in settings
• Token displayed in console on worker start
• Token required as query param (?token=xxx) or header (Authorization: Bearer xxx)
• Cookie-based session after first auth for convenience

Option 2: Basic Auth

{
  "CLAUDE_MEM_AUTH_USERNAME": "claude",
  "CLAUDE_MEM_AUTH_PASSWORD": "secret"
}

Implementation Details

1. Middleware in worker-service.ts:

   • Check if CLAUDE_MEM_WORKER_HOST !== '127.0.0.1' AND auth is enabled
   • Validate token/credentials on all routes except /health
   • Return 401 Unauthorized if invalid

2. Auto-enable suggestion:

   • When user sets WORKER_HOST to 0.0.0.0, show warning in logs
   • Suggest enabling authentication

3. Web Viewer UI:

   • Login page when auth is required
   • Store token in localStorage after successful auth

Use Cases

• Accessing web viewer from phone/tablet on same network
• Viewing memory timeline from another workstation
• Team environments where multiple developers share a network

Security Considerations

• Token should be cryptographically random (at least 32 chars)
• Rate limiting on auth attempts to prevent brute force
• Clear warning in docs about network exposure risks
• Consider HTTPS support for encrypted transport (future enhancement)

Alternatives Considered

• Reverse proxy (Traefik/nginx): Works but adds complexity for simple use case
• VPN only: Not always available on home networks
• No auth: Current state, insecure for network exposure

🤖 Generated with Claude Code