A lightweight, secure reverse proxy with Google OAuth authentication for OpenCode. Protects your OpenCode server by enforcing authentication before proxying requests.

Note: This project is not built by the OpenCode team and is not affiliated with OpenCode in any way.

• 🔐 Google OAuth 2.0 - PKCE flow for secure authentication
• 🍪 Session Management - HMAC-signed secure session cookies
• 🔄 Reverse Proxy - Seamless forwarding to upstream OpenCode server
• 🌐 WebSocket Support - Full WebSocket proxying with authentication
• 📡 SSE Streaming - Real-time log streaming with automatic reconnection
• 🏥 Health Checks - Built-in health monitoring endpoints
• 🛠️ Debug Tools - Log viewer UI and SSE test tools
• 🏗️ Modular Architecture - Clean, maintainable, testable codebase

• Bun >= 1.0.0
• Google OAuth credentials (Client ID and Secret)
• OpenCode server running (for proxying)

1. Install dependencies:

   bun install

2. Create .env file:

   SESSION_SECRET=your-very-long-secret-key-at-least-32-characters
   GOOGLE_REDIRECT_CLIENT_ID=your-client-id
   GOOGLE_REDIRECT_CLIENT_SECRET=your-client-secret
   GOOGLE_REDIRECT_URI=http://localhost:4096/auth/google/callback
   PORT=4096
   TARGET_HOST=127.0.0.1
   TARGET_PORT=4097

3. Run the server:

   bun run dev    # Development with watch
   bun run start  # Production

4. Authenticate:

   • Visit http://localhost:4096/auth/google/start
   • Complete Google OAuth flow
   • You'll be redirected back with a session cookie

# Required
SESSION_SECRET=your-very-long-secret-key-at-least-32-characters-long
GOOGLE_REDIRECT_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_REDIRECT_CLIENT_SECRET=your-google-client-secret

# Optional - defaults shown
GOOGLE_REDIRECT_URI=http://localhost:4096/auth/google/callback
PORT=4096
TARGET_HOST=127.0.0.1
TARGET_PORT=4097
TOKEN_PATH=~/.opencode-gateway/google-auth.json
SESSION_COOKIE_NAME=opencode_session
COOKIE_SECURE=true
TRUST_PROXY=false

1. User visits /auth/google/start → Redirected to Google OAuth
2. Google redirects back to /auth/google/callback with authorization code
3. Proxy exchanges code for tokens using PKCE verification
4. Tokens stored locally and secure session cookie set
5. Subsequent requests with valid session cookie are proxied to OpenCode

┌─────────┐         ┌──────────┐         ┌─────────┐         ┌─────────────┐
│ Browser │ ──────> │  Proxy   │ ──────> │ Google  │ ──────> │   Proxy     │
│         │ <────── │          │ <────── │  OAuth  │ <────── │  (callback) │
└─────────┘         └──────────┘         └─────────┘         └─────────────┘
     │                    │                                           │
     │                    │                                           │
     │                    ▼                                           ▼
     │              [Session Cookie]                            [Store Tokens]
     │                    │                                           │
     └────────────────────┼──────────────────────────────────────────┘
                          │
                          ▼
                   [Authenticated Requests]
                          │
                          ▼
                   [OpenCode Server]

The proxy provides real-time log streaming via Server-Sent Events (SSE).

Visit http://localhost:4096/logs after authenticating for a terminal-style log viewer with:

• Real-time log streaming
• Color-coded log levels
• Auto-scroll to latest entries
• Clear logs functionality

const eventSource = new EventSource('/logs/stream', { 
  withCredentials: true 
})

eventSource.onmessage = (event) => {
  const logEntry = JSON.parse(event.data)
  console.log(logEntry)
}

eventSource.onerror = (error) => {
  console.error('SSE connection error:', error)
}

• ✅ Automatic reconnection on connection loss
• ✅ Real-time log streaming
• ✅ Structured log format
• ✅ Supports Last-Event-ID for reconnection

The proxy uses a modular architecture with clear separation of concerns:

src/
├── core/          # Pure logic (auth, session, proxy decisions)
├── adapters/      # Runtime implementations (logger, storage, proxy)
├── middleware/    # High-level coordination (auth flow)
└── views/         # HTML templates

• RequestContext Pattern: Dependency injection for testability
• Core/Adapters Separation: Pure logic vs side effects
• Zero Duplication: All shared logic in reusable modules

opencode-gateway/
├── proxy.ts                    # Main entry point
├── src/
│   ├── types.ts                # Type definitions
│   ├── config.ts               # Configuration loader
│   ├── core/                   # Pure logic modules
│   │   ├── auth.ts             # OAuth & PKCE
│   │   ├── session.ts          # Session management
│   │   ├── proxy.ts            # Proxy logic
│   │   ├── headers.ts          # Security headers
│   │   └── http-utils.ts       # HTTP utilities
│   ├── adapters/               # Implementations
│   │   ├── logger/             # Logging adapters
│   │   ├── storage/            # Token storage
│   │   └── proxy/              # Proxy server
│   ├── middleware/             # Coordination
│   │   └── auth-flow.ts        # Auth flow
│   └── views/                  # HTML templates
└── tests/                      # Test suite

bun test

The test suite includes unit tests for core modules (auth, session, config, http-utils) with test helpers for RequestContext mocking.

• ✅ PKCE Flow: Prevents authorization code interception
• ✅ HMAC Sessions: Tamper-proof session cookies
• ✅ State TTL: OAuth state expires after 10 minutes
• ✅ Secret Validation: Warnings for weak secrets
• ✅ Hop-by-Hop Headers: Proper header stripping
• ✅ Security Headers: HSTS, CSP, X-Frame-Options

1. Use strong secrets: At least 32 characters for SESSION_SECRET
2. HTTPS in production: Set COOKIE_SECURE=true for HTTPS
3. Environment variables: Store secrets in .env, not in code
4. Token storage: Keep token file secure (default: ~/.opencode-gateway/)

• Ensure .env has SESSION_SECRET set
• Or set it as an environment variable
• Minimum 32 characters recommended

• Check GOOGLE_REDIRECT_CLIENT_ID and GOOGLE_REDIRECT_CLIENT_SECRET
• Verify credentials in Google Cloud Console
• Ensure redirect URI matches exactly

• Ensure session cookie is sent with upgrade request
• Check that upstream server supports WebSocket
• Verify proxy is handling upgrade requests correctly

• Verify TARGET_HOST and TARGET_PORT are correct
• Ensure OpenCode server is running
• Check firewall/network settings

This is a focused project, but improvements are welcome! Key areas:

• Integration tests
• Additional storage adapters
• Performance optimizations
• Documentation improvements

See CONTRIBUTING.md for guidelines.

MIT License - see LICENSE file for details

Built with:

• Bun - Fast JavaScript runtime
• http-proxy - HTTP proxying
• TypeScript - Type safety