Skip to content

feat: add Better Auth device authorization flow#465

Open
nhyiramante1 wants to merge 1 commit into
mainfrom
feat/better-auth-device-flow
Open

feat: add Better Auth device authorization flow#465
nhyiramante1 wants to merge 1 commit into
mainfrom
feat/better-auth-device-flow

Conversation

@nhyiramante1

@nhyiramante1 nhyiramante1 commented Jun 12, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds Better Auth device authorization to the Hono backend, building on the optional Better Auth foundation in PR #460.

This provides the backend flow needed for clients such as the Word taskpane or Google Docs add-on to authenticate through an external browser and receive a Bearer token through polling.

Changes

  • Add Better Auth's deviceAuthorization plugin
  • Add configurable comma-separated device client ID allowlist
  • Add /api/device browser approval page
  • Add explicit Google sign-in and Approve/Deny flow
  • Add debug-only taskpane simulator at /api/debug/device
  • Poll for device authorization without relying on cookies
  • Verify the returned Bearer token through /api/protected
  • Forward device client ID configuration through Docker Compose
  • Add local environment setup guidance

Security

  • The private device_code remains with the polling client
  • Only the public user_code is included in the approval URL
  • Access tokens are held in memory and are not persisted or displayed
  • Dynamic browser content uses textContent rather than innerHTML
  • An empty client-ID allowlist rejects all device requests
  • Approval requires an authenticated Google session and explicit user action

Verification

  • Better Auth migration created the deviceCode table
  • Backend typecheck passed
  • Backend build passed
  • Existing backend tests passed: 13/13
  • Backend Docker image built successfully with better-sqlite3
  • Complete the full flow manually through /api/debug/device
  • Verify approval, denial, expiration, and polling behavior

Scope

This PR does not:

  • Remove or modify Auth0
  • Integrate the flow into the production Word or Google Docs frontend
  • Protect existing OpenAI or logging routes
  • Enable Better Auth automatically in deployed environments
  • Add remote Jenkins credentials or run deployment migrations

Branching

This is a stacked PR based on feat/better-auth-backend-foundation from PR #460. After PR #460 merges, this PR can be rebased or have its base changed to main.

@nhyiramante1 nhyiramante1 requested a review from kcarnold June 12, 2026 18:43
Base automatically changed from feat/better-auth-backend-foundation to main June 12, 2026 20:41
@kcarnold

Copy link
Copy Markdown
Contributor

To test this, I had to create a .env file with:

POSTHOG_PROJECT_TOKEN=...
BETTER_AUTH_ENABLED=true
BETTER_AUTH_SECRET=...
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
BETTER_AUTH_DEVICE_CLIENT_IDS=writing-tools-device-poc

with the appropriate secrets filled in for the ...s.

Then I ran npx auth@latest migrate to get the db schema, then DEBUG=true npm run dev to get the dev server running in debug mode.

Then I went to https://localhost:3000/api/debug/device and clicked the button there.

I got an error from Google:

Error 400: invalid_request
The loopback flow has been blocked in order to keep users secure. Follow the Loopback IP Address flow migration guide linked in the developer docs below to migrate your app to an alternative method.
Request details: flowName=GeneralOAuthFlow
Related developer documentation

The linked page doesn't seem to mention anything about auth during development.

How did you get this to work locally?

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.

2 participants