Skip to content

feat: add Bearer token API key authentication#2

Open
onurgoz wants to merge 1 commit into
huseyinstif:mainfrom
onurgoz:feat/api-key-auth
Open

feat: add Bearer token API key authentication#2
onurgoz wants to merge 1 commit into
huseyinstif:mainfrom
onurgoz:feat/api-key-auth

Conversation

@onurgoz

@onurgoz onurgoz commented Mar 9, 2026

Copy link
Copy Markdown

Summary

  • Add --api-key <KEY> CLI flag and OCULOS_API_KEY env var for API authentication
  • Auto-generate a cryptographically secure key (oculos_<32-byte hex>) when none is provided
  • Axum middleware layer enforces Authorization: Bearer <KEY> on all HTTP endpoints (/windows/**, /interact/**, /hwnd/**, /health, /ws)
  • Browser WebSocket connections authenticated via ?token=<KEY> query parameter (since browser WS API cannot send custom headers)
  • Dashboard login screen with localStorage persistence; 401 responses trigger automatic logout
  • Constant-time key comparison to prevent timing side-channel attacks
  • Fail-closed auth design (returns 500 if auth layer is misconfigured)
  • MCP mode (--mcp) bypasses auth entirely (stdin/stdout, no network involved)
  • Recorder-exported scripts (Python/JS/curl) include auth headers
  • README updated with full Authentication section and all curl examples updated

Changed files

File Change
Cargo.toml Added rand = "0.8" dependency
src/auth.rs New — key generation, auth middleware, constant-time compare
src/main.rs --api-key CLI arg, env var, wiring
src/api/mod.rs Middleware + Extension layer on router
src/api/ws.rs Updated doc comments
static/index.html Login overlay, auth headers on all fetches/WS, 401 handling
README.md Auth section, updated curl examples, API table auth note

Test plan

  • cargo build compiles without errors on all 3 platforms
  • Start without --api-key → random key printed to console
  • Start with --api-key mykey → "Using provided API key" logged
  • Start with OCULOS_API_KEY=mykey → same behavior
  • curl http://localhost:7878/windows → 401 Unauthorized
  • curl -H "Authorization: Bearer <key>" http://localhost:7878/windows → 200 OK
  • Dashboard shows login screen on first visit
  • Wrong key → "Invalid API key" error shown
  • Correct key → dashboard loads, key saved in localStorage
  • Refresh page → auto-login with saved key (no login screen)
  • WebSocket connects with ?token= and receives events
  • --mcp mode works without any auth prompts
  • After server restart with new key → dashboard shows 401, login screen reappears

- Add --api-key CLI flag and OCULOS_API_KEY env var support
- Auto-generate cryptographically secure key (oculos_<hex>) if none provided
- Axum middleware layer validates Authorization: Bearer header on all routes
- Support ?token= query param for browser WebSocket connections
- Dashboard login screen with localStorage persistence and 401 auto-logout
- Constant-time key comparison to prevent timing attacks
- Fail-closed design (500 if auth layer misconfigured)
- MCP mode bypasses auth (stdin/stdout, no network)
- Recorder exports include auth headers in generated code
- README: auth section with usage examples, curl commands updated
aadya940 added a commit to aadya940/oculos that referenced this pull request Apr 5, 2026
slim find_ui_elements and add sense to prompt
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