Skip to content

feat(server): add OAuth device flow for Google authentication#15

Merged
jgpruitt merged 2 commits into
mainfrom
feature/server-oauth-google
Apr 7, 2026
Merged

feat(server): add OAuth device flow for Google authentication#15
jgpruitt merged 2 commits into
mainfrom
feature/server-oauth-google

Conversation

@jgpruitt

@jgpruitt jgpruitt commented Apr 7, 2026

Copy link
Copy Markdown
Collaborator

Summary

Implements OAuth device flow (RFC 8628) for Google authentication (Chunk 7 of server implementation).

Changes

New Files

  • packages/server/auth/types.ts - Device flow and OAuth types
  • packages/server/auth/device-flow.ts - In-memory device state management
  • packages/server/auth/device-flow.test.ts - 21 unit tests for state management
  • packages/server/auth/providers/google.ts - Google OAuth configuration
  • packages/server/auth/providers/index.ts - Provider registry
  • packages/server/auth/index.ts - Module exports
  • packages/server/handlers/auth.ts - HTTP request handlers

Endpoints Implemented

Endpoint Method Description
/api/v1/auth/device/code POST CLI initiates device authorization
/api/v1/auth/device/token POST CLI polls for session token
/api/v1/auth/device/verify GET User enters code (HTML form)
/api/v1/auth/device/verify POST User submits code, redirects to Google
/api/v1/auth/callback/:provider GET OAuth callback, creates session

Device Flow

CLI                           Server                        Browser
 │                              │                              │
 │─POST /device/code───────────>│                              │
 │<──{deviceCode, userCode}─────│                              │
 │                              │                              │
 │  "Visit /device/verify       │                              │
 │   Enter code: ABCD-1234"     │                              │
 │                              │                              │
 │                              │<────GET /device/verify───────│
 │                              │─────HTML form───────────────>│
 │                              │                              │
 │                              │<────POST (code)──────────────│
 │                              │─────Redirect to Google──────>│
 │                              │                              │
 │                              │<────GET /callback/google─────│
 │                              │─────"Success! Close window"─>│
 │                              │                              │
 │─POST /device/token──────────>│                              │
 │<──{sessionToken, identity}───│                              │

Features

  • User-friendly 8-character codes (XXXX-XXXX format, no ambiguous chars)
  • 15-minute device code expiration
  • 5-second minimum polling interval (rate limiting)
  • CSRF protection via OAuth state parameter
  • Clean HTML pages for code entry and success/error

Environment Variables Required

GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

Test Results

234 pass (all server tests)
21 device flow tests

Next Chunks

  • Chunk 8: OAuth GitHub (feature/server-oauth-github)
  • Chunk 9: Rate limiting (feature/server-rate-limit)

jgpruitt added 2 commits April 7, 2026 15:26
Implements RFC 8628 (OAuth 2.0 Device Authorization Grant) for Google OAuth.

Device flow endpoints:
- POST /api/v1/auth/device/code - CLI initiates device authorization
- POST /api/v1/auth/device/token - CLI polls for session token
- GET /api/v1/auth/device/verify - User enters code (HTML form)
- POST /api/v1/auth/device/verify - User submits code, redirects to Google
- GET /api/v1/auth/callback/:provider - OAuth callback, creates session

Features:
- In-memory device state with automatic expiration (15 min)
- User-friendly 8-char codes (XXXX-XXXX format)
- Rate limiting for token polling (5s minimum interval)
- CSRF protection via OAuth state parameter
- Clean HTML pages for code entry and success/error

Files added:
- auth/types.ts - Device flow and OAuth types
- auth/device-flow.ts - State management (21 unit tests)
- auth/providers/google.ts - Google OAuth config
- auth/providers/index.ts - Provider registry
- handlers/auth.ts - HTTP request handlers

Updated router.ts to wire up specific auth routes instead of wildcard.
Updated tests to reflect new implementation.

234 tests passing.
@jgpruitt jgpruitt merged commit 2ea4e7e into main Apr 7, 2026
2 checks passed
@jgpruitt jgpruitt deleted the feature/server-oauth-google branch April 7, 2026 20:30
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