feat: add RFC 8252 loopback port flexibility for native apps

[mattzcarey]

Summary

• Add RFC 8252 Section 7.3 compliance for loopback redirect URI port handling
• Native apps (VS Code, Cursor, CLI tools) can now use ephemeral ports obtained from the OS at runtime
• Loopback URIs (127.x.x.x, ::1) match on scheme, host, and path while ignoring port; non-loopback URIs still require exact match

Background

Per RFC 8252 Section 7.3:

While redirect URIs using localhost (i.e., "http://localhost:{port}/{path}") function similarly to loopback IP redirects, the use of localhost is NOT RECOMMENDED. [...] To perform authorization using loopback interface redirect URIs, the native app [...] performs a Loopback Interface Redirection by constructing the redirect_uri from the loopback IP address [...] and whatever port the HTTP server is listening on.

The authorization server MUST allow any port to be specified at the time of the request for loopback IP redirect URIs, to accommodate clients that obtain an available ephemeral port from the operating system at the time of the request.

Native desktop applications like VS Code, Cursor, and CLI tools typically:

1. Start a local HTTP server on an ephemeral port
2. Register a redirect URI like http://127.0.0.1:8080/callback
3. But at runtime, the OS assigns a different port (e.g., http://127.0.0.1:52431/callback)

This change enables these native apps to work correctly by allowing any port for loopback redirect URIs.

Implementation

Added two helper functions:

• isLoopbackUri() - Detects loopback addresses (127.0.0.0/8 and ::1)
• isValidRedirectUri() - Validates redirect URIs with RFC 8252 loopback support

Replaced all 3 occurrences of redirectUris.includes(redirectUri) with isValidRedirectUri(redirectUri, clientInfo.redirectUris):

1. Authorization request parsing
2. Token exchange
3. completeAuthorization

Test Plan

• All 215 existing tests pass
• Manual testing with native app using ephemeral port
• Verify non-loopback URIs still require exact match
• Verify loopback URIs with different schemes are rejected
• Verify loopback URIs with different paths are rejected

Fixes #35

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/workers-oauth-provider/@cloudflare/workers-oauth-provider@145

commit: 9a57612

[changeset-bot]

🦋 Changeset detected

Latest commit: 9a57612

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@cloudflare/workers-oauth-provider	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR