fix(auth): complete device authorization grant support

[gjtorikian]

The device authorization grant (RFC 8628) was partially implemented, leaving CLIs that follow the spec unable to test it against the emulator (#62).

What changed

• Form-encoded bodies now accepted on both endpoints, for every grant. /user_management/authorize/device and /user_management/authenticate previously called parseJsonBody and rejected application/x-www-form-urlencoded, which RFC 8628 §3.1/§3.2 require and which is what CLIs send. A new parseOAuthBody helper dispatches on Content-Type — JSON goes through the existing parseJsonBody, form-encoded through c.req.parseBody() — and returns the same Record<string, unknown> the handlers already index into.
  • This mirrors production, verified against the WorkOS API source: /user_management/authenticate accepts both media types on every grant (Nest's default urlencoded parser is active, and the edge proxy documents both content types for that path), not just device_code — even though the docs only show form-encoded for the device_code example. Scoping form-encoded to device_code alone would be more restrictive than production and produce false failures, so the emulator accepts form-encoded everywhere production does.
• verification_uri is now resolvable. It was hardcoded to the unreachable http://localhost:0/user_management/authorize/device/verify. The emulator's baseUrl is now threaded into formatDeviceAuthorization, so the URL points at the running instance.
• Verify page served. Added GET /user_management/authorize/device/verify returning a styled HTML confirmation page. Because the emulator auto-approves device authorization with the first seeded user, the page confirms rather than collects a user_code, so a CLI that opens verification_uri in a browser no longer hits a 404. It is registered as a public path (like the /user_management/authorize login page), since a browser cannot send a bearer token.

Why

Device authorization is the standard grant for CLIs and other input-constrained devices. Without form-encoded support, a spec-compliant CLI couldn't even start the flow against the emulator; and the returned verification_uri was both unresolvable and pointed at a route that didn't exist.

Closes #62

[greptile-apps]

Greptile Summary

The PR completes device authorization grant support by accepting form-encoded OAuth requests, returning a verification URL based on the actual bound server address, and serving a public confirmation page.

• Adds a shared JSON/form OAuth body parser and applies it to device authorization and authentication grants.
• Propagates the post-bind URL through the mutable route context and seed lifecycle.
• Adds route-level and real-HTTP coverage for form requests, the verification page, and ephemeral ports.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the actual bound URL now reaches the device authorization handler through the shared mutable context, and real-HTTP coverage verifies the ephemeral-port path.

Important Files Changed

Filename	Overview
src/index.ts	Updates the shared route context and seeding with the actual post-bind URL, resolving the previously reported ephemeral-port failure.
src/core/server.ts	Introduces the mutable route context used after binding and makes the static browser verification endpoint public.
src/core/middleware/error-handler.ts	Adds OAuth request parsing for JSON and form-encoded bodies while preserving standardized parse errors.
src/workos/routes/auth.ts	Uses the OAuth parser, derives device verification URLs from the live route context, and serves the confirmation page.
src/e2e.spec.ts	Exercises device authorization over real HTTP with port 0 and verifies the returned URL uses the actual bound address.
src/workos/routes/auth.spec.ts	Covers form-encoded device and password grants, base-URL derivation, and the verification page.
src/workos/login-page.ts	Adds an escaped static HTML renderer for the device approval confirmation.
src/workos/helpers.ts	Formats device authorization responses using the supplied runtime base URL.

Sequence Diagram

sequenceDiagram
  participant CLI
  participant Emulator
  participant DeviceRoute
  participant Browser
  CLI->>Emulator: POST /authorize/device (form encoded)
  Emulator->>DeviceRoute: Parse OAuth body
  DeviceRoute-->>CLI: device_code + bound verification_uri
  CLI->>Browser: Open verification_uri
  Browser->>Emulator: GET /authorize/device/verify
  Emulator-->>Browser: Device approved page
  CLI->>Emulator: POST /authenticate (device_code)
  Emulator-->>CLI: Access token

Loading

_{Reviews (5): Last reviewed commit: "fix(server): reflect bound port in route..." | Re-trigger Greptile}

[greptile-apps]

Ephemeral verification URI remains unreachable

When the emulator starts with port 0, the route context retains the pre-bind http://localhost:0 base URL after the actual port is resolved, causing device authorization to return a verification_uri that browsers cannot reach. This test substitutes another non-listening address and checks only string interpolation, so it still passes without covering the broken startup path.

Knowledge Base Used:

• Core runtime and server machinery
• Authentication and session flows

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/workos/routes/auth.spec.ts
Line: 1027-1034

Comment:
**Ephemeral verification URI remains unreachable**

When the emulator starts with port `0`, the route context retains the pre-bind `http://localhost:0` base URL after the actual port is resolved, causing device authorization to return a `verification_uri` that browsers cannot reach. This test substitutes another non-listening address and checks only string interpolation, so it still passes without covering the broken startup path.

**Knowledge Base Used:**
- [Core runtime and server machinery](https://app.greptile.com/workos/-/custom-context/knowledge-base/workos/emulate/-/docs/core-runtime-and-server.md)
- [Authentication and session flows](https://app.greptile.com/workos/-/custom-context/knowledge-base/workos/emulate/-/docs/authentication-and-session-flows.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.