dev-oauth-proxy

Configure Google OAuth once with http://localhost:3000/auth/google/callback and never touch it again.

Zero-config OAuth proxy for local development. Route multiple apps through a single port for OAuth callbacks.

Pure bash. No Docker. No Node. Just install and run.

Installation

# npm (easiest)
npm install -g dev-oauth-proxy

# Homebrew
brew tap SaharBarak/tap && brew install dop

# curl
curl -fsSL https://raw.githubusercontent.com/SaharBarak/dev-oauth-proxy/main/install.sh | bash

Quick Start

dop init          # Initialize
dop scan          # Auto-detect running apps
dop start         # Start proxy
dop dashboard     # Live status view

---

Command Previews

dop init

$ dop init

[info] Initializing dop configuration...
[ok] Configuration initialized at ~/.config/dop/config
[info] Next steps:
  1. dop scan       # Auto-detect running apps
  2. dop start      # Start the proxy
  3. dop dashboard  # View live status

dop add

$ dop add frontend 3001
$ dop add api 4000 /api
$ dop add admin 3002 /admin

[ok] Added app 'frontend' on port 3001 (path: /)
[ok] Added app 'api' on port 4000 (path: /api)
[ok] Added app 'admin' on port 3002 (path: /admin)

dop ls

$ dop ls

NAME                 PORT       PATH
----                 ----       ----
frontend             3001       /
api                  4000       /api
admin                3002       /admin

[info] Proxy will run on: http://localhost:3000

dop scan

$ dop scan

[info] Scanning for running dev servers...

PORT         STATUS   PROCESS              ACTION
----         ------   -------              ------
:3000        ACTIVE   next-server
:3001        ACTIVE   node                 (registered)
:4000        ACTIVE   python3
:5173        ACTIVE   vite
:8080        ACTIVE   java

[ok] Found 5 active server(s)

[info] To add a detected server:
  dop add <name> <port>

[info] Or auto-add all with:
  dop scan --add

dop scan --add

$ dop scan --add

[info] Auto-adding detected servers...
[ok] Added next-server on port 3000
[ok] Added python3 on port 4000
[ok] Added vite on port 5173
[ok] Added java on port 8080
[ok] Added 4 server(s)

dop dashboard

$ dop dashboard

╔═══════════════════════════════════════════════════════════════════╗
║                    dop - Dev OAuth Proxy                          ║
╚═══════════════════════════════════════════════════════════════════╝

  Proxy: ● RUNNING on http://localhost:3000 (PID: 12345)

  OAuth Callbacks (configure these once, never change):
    Google:  http://localhost:3000/auth/google/callback
    GitHub:  http://localhost:3000/auth/github/callback
    GitLab:  http://localhost:3000/auth/gitlab/callback
    Auth0:   http://localhost:3000/auth/auth0/callback

  Registered Apps:
  ┌──────────────────────┬────────┬────────────────┬──────────┐
  │ NAME                 │ PORT   │ PATH           │ STATUS   │
  ├──────────────────────┼────────┼────────────────┼──────────┤
  │ frontend             │ 3001   │ /              │ ● UP     │
  │ api                  │ 4000   │ /api           │ ● UP     │
  │ admin                │ 3002   │ /admin         │ ○ DOWN   │
  └──────────────────────┴────────┴────────────────┴──────────┘

  ─────────────────────────────────────────────────────────────────
  Press Ctrl+C to exit | Refreshing every 2s

dop sync

$ dop sync

[info] Found project config: /path/to/project/.dop.yaml
[info] Syncing apps from project config...
[ok] Added frontend on port 3001 (path: /)
[ok] Added api on port 4000 (path: /api)
[ok] Added admin on port 3002 (path: /admin)

[ok] Sync complete!

dop status

$ dop status

[ok] Proxy running on http://localhost:3000 (PID: 12345)
[info] Daemon: loaded

NAME                 PORT       PATH
----                 ----       ----
frontend             3001       /
api                  4000       /api
admin                3002       /admin

[info] Proxy will run on: http://localhost:3000

dop doctor

$ dop doctor

[info] Checking system requirements...
[ok] socat: /usr/local/bin/socat
[ok] curl: /usr/bin/curl
[ok] nc: /usr/bin/nc
[ok] pfctl: /sbin/pfctl (kernel-level forwarding available)
[ok] launchctl: available (daemon mode supported)
[ok] config: ~/.config/dop/config

[ok] All good! Ready to proxy.

dop --help

$ dop --help

dop - Dev OAuth Proxy v0.2.0

Configure OAuth once. Never touch it again.
Route multiple apps through a single port for OAuth callbacks.

USAGE:
    dop <command> [options]

COMMANDS:
    init                    Initialize configuration
    add <name> <port> [path]  Add an app
    rm <name>               Remove an app
    ls                      List configured apps
    scan                    Auto-detect running dev servers
    dashboard               Live dashboard of all apps
    start [-d]              Start proxy (-d for daemon mode)
    stop                    Stop proxy daemon
    status                  Show proxy status
    logs                    Tail proxy logs
    sync                    Sync with project .dop.yaml config
    config                  Show current config
    doctor                  Check system requirements

OAUTH PROVIDERS SUPPORTED:
    Google:  http://localhost:3000/auth/google/callback
    GitHub:  http://localhost:3000/auth/github/callback
    GitLab:  http://localhost:3000/auth/gitlab/callback
    Auth0:   http://localhost:3000/auth/auth0/callback
    Generic: http://localhost:3000/oauth/callback

---

Features

Multi-Provider OAuth Support

Configure once in your OAuth provider, works forever:

Provider	Callback URL
Google	http://localhost:3000/auth/google/callback
GitHub	http://localhost:3000/auth/github/callback
GitLab	http://localhost:3000/auth/gitlab/callback
Auth0	http://localhost:3000/auth/auth0/callback
Generic	http://localhost:3000/oauth/callback

Team Sharing via Git

Create .dop.yaml in your project root:

# .dop.yaml - Commit to git for team sharing
name: my-project

apps:
  - name: frontend
    port: 3001
    path: /
  - name: api
    port: 4000
    path: /api
  - name: admin
    port: 3002
    path: /admin

oauth:
  providers:
    - google
    - github

Team members just run:

dop sync    # Loads config from .dop.yaml
dop start   # Ready to go

---

The Problem

Every time your local dev app runs on a different port, you have to:

1. Go to Google Cloud Console
2. Update OAuth redirect URIs
3. Wait for propagation
4. Lose 30 minutes of your life

The Solution

Run all your OAuth callbacks through a single port. Configure once. Never touch it again.

┌─────────────────────────────────────────────────┐
│              dev-oauth-proxy                     │
│              localhost:3000                      │
├─────────────────────────────────────────────────┤
│                                                  │
│   /app1/*  ──────►  localhost:3001 (frontend)   │
│   /app2/*  ──────►  localhost:3002 (admin)      │
│   /api/*   ──────►  localhost:4000 (backend)    │
│                                                  │
│   /auth/google/callback  ──►  originating app   │
│                                                  │
└─────────────────────────────────────────────────┘

---

How It Works

1. Proxy listens on port 3000 (or your configured port)
2. Routes requests by path prefix to your apps
3. OAuth callbacks are intercepted and routed to the originating app
4. Apps run on any port - proxy handles the routing

OAuth Flow

1. User clicks "Login with Google" on your app (localhost:3001)
2. App redirects to Google with callback: localhost:3000/auth/google/callback
3. Google authenticates user, redirects to localhost:3000/auth/google/callback
4. Proxy intercepts callback, identifies originating app
5. Proxy redirects to localhost:3001/auth/google/callback with tokens
6. Your app receives the OAuth callback

---

Configuration

Config is stored in ~/.config/dop/:

~/.config/dop/
├── config    # Main configuration
├── apps      # Registered apps
└── sessions/ # OAuth session tracking

Config Options

# ~/.config/dop/config

PROXY_PORT=3000              # Port the proxy listens on
PROXY_HOST=localhost         # Host to bind to
LOG_LEVEL=info               # debug, info, warn, error

# OAuth callback paths (space-separated)
OAUTH_PATHS="/auth/google/callback /auth/github/callback ..."

---

Dependencies

• Required: curl (pre-installed on macOS)
• Recommended: socat - brew install socat

Troubleshooting

Port already in use

dop doctor          # Check what's using the port
lsof -i :3000       # See process on port 3000

socat not found

brew install socat

The proxy will work without socat using netcat, but with limited functionality.

App not receiving callbacks

1. Check your app is running: dop status
2. Verify the callback path matches your app's OAuth config
3. Check logs: dop logs

---

License

MIT

Contributing

PRs welcome! Keep it simple, keep it bash.