github-starred/better-auth
2
0
Fork 0
mirror of https://github.com/better-auth/better-auth.git synced 2026-05-23 07:18:56 -05:00
Code Issues 2.5k Packages Projects Releases 112 Wiki Activity

baseURL validation breaks electron custom protocols #2659

New Issue
Open
opened 2026-03-13 10:11:23 -05:00 by GiteaMirror · 6 comments
GiteaMirror commented 2026-03-13 10:11:23 -05:00
Owner
Copy Link

Originally created by @poeck on GitHub (Jan 6, 2026).

Originally assigned to: @himself65, @bytaesu on GitHub.

Is this suited for github?

  • Yes, this is suited for github

To Reproduce

  1. Initialize a better-auth client instance within an Electron application.
  2. Set the baseURL to a custom protocol as recommended by Electron security best practices (e.g., app://blinkdisk or blinkdisk://auth).
  3. Attempt to initialize the client or make a request.
  4. Observe the error thrown due to the validation logic introduced in PR #5902, which strictly enforces http or https protocols
BetterAuthError: Invalid base URL: electronapp://api. URL must include 'http://' or 'https://'

Current vs. Expected behavior

Current Behavior: The client throws an error or fails to initialize because the baseURL validation logic explicitly checks for http or https prefixes. It rejects valid Electron custom protocols (like app://, electron://, or strictly defined custom schemes), making it impossible to use better-auth with secure, local-file-serving schemes in desktop apps.

Expected Behavior: The baseURL validation should allow custom protocols (such as app://, file://, or vendor-specific schemes) to support desktop application environments (Electron, Tauri, etc.). Alternatively, there should be an option to disable strict protocol validation for specific environments.

What version of Better Auth are you using?

1.4.10

System info

{
  "system": {
    "platform": "linux",
    "arch": "x64",
    "version": "#1-NixOS SMP PREEMPT_DYNAMIC Fri Dec 12 17:42:47 UTC 2025",
    "release": "6.18.1",
    "cpuCount": 24,
    "cpuModel": "AMD Ryzen AI 9 HX 370 w/ Radeon 890M",
    "totalMemory": "30.47 GB",
    "freeMemory": "19.95 GB"
  },
  "node": {
    "version": "v24.12.0",
    "env": "development"
  },
  "packageManager": {
    "name": "npm",
    "version": "11.6.2"
  },
  "frameworks": null,
  "databases": null,
  "betterAuth": {
    "version": "Unknown",
    "config": null
  }
}

Which area(s) are affected? (Select all that apply)

Client

Auth config (if applicable)

import { betterAuth } from "better-auth"
export const auth = betterAuth({
  baseURL: "electronapp://api",
  emailAndPassword: {  
    enabled: true
  },
});

Additional context

I am the developer of BlinkDisk, and we follow Electron's security best practices, specifically Guideline 18: Avoid usage of the file:// protocol and prefer usage of custom protocols. Consequently, our app runs on a custom protocol (e.g., blinkdiskapp://), not http or https, for both the frontend and backend.

The recent change in PR #5902 introduced strict validation that assumes a web-only environment. This breaks compatibility with secure Electron setups where the baseURL is using a custom scheme. We need a way to bypass this check or have the validator accept custom schemes to maintain security standards without breaking authentication.

Originally created by @poeck on GitHub (Jan 6, 2026). Originally assigned to: @himself65, @bytaesu on GitHub. ### Is this suited for github? - [x] Yes, this is suited for github ### To Reproduce 1. Initialize a better-auth client instance within an Electron application. 2. Set the baseURL to a custom protocol as recommended by Electron security best practices (e.g., app://blinkdisk or blinkdisk://auth). 3. Attempt to initialize the client or make a request. 4. Observe the error thrown due to the validation logic introduced in PR #5902, which strictly enforces http or https protocols ``` BetterAuthError: Invalid base URL: electronapp://api. URL must include 'http://' or 'https://' ``` ### Current vs. Expected behavior **Current Behavior:** The client throws an error or fails to initialize because the baseURL validation logic explicitly checks for http or https prefixes. It rejects valid Electron custom protocols (like app://, electron://, or strictly defined custom schemes), making it impossible to use better-auth with secure, local-file-serving schemes in desktop apps. **Expected Behavior:** The baseURL validation should allow custom protocols (such as app://, file://, or vendor-specific schemes) to support desktop application environments (Electron, Tauri, etc.). Alternatively, there should be an option to disable strict protocol validation for specific environments. ### What version of Better Auth are you using? 1.4.10 ### System info ```bash { "system": { "platform": "linux", "arch": "x64", "version": "#1-NixOS SMP PREEMPT_DYNAMIC Fri Dec 12 17:42:47 UTC 2025", "release": "6.18.1", "cpuCount": 24, "cpuModel": "AMD Ryzen AI 9 HX 370 w/ Radeon 890M", "totalMemory": "30.47 GB", "freeMemory": "19.95 GB" }, "node": { "version": "v24.12.0", "env": "development" }, "packageManager": { "name": "npm", "version": "11.6.2" }, "frameworks": null, "databases": null, "betterAuth": { "version": "Unknown", "config": null } } ``` ### Which area(s) are affected? (Select all that apply) Client ### Auth config (if applicable) ```typescript import { betterAuth } from "better-auth" export const auth = betterAuth({ baseURL: "electronapp://api", emailAndPassword: { enabled: true }, }); ``` ### Additional context I am the developer of [BlinkDisk](https://github.com/blinkdisk/blinkdisk), and we follow Electron's security best practices, specifically [Guideline 18: Avoid usage of the file:// protocol and prefer usage of custom protocols](https://www.google.com/search?q=%5Bhttps://www.electronjs.org/docs/latest/tutorial/security%2318-avoid-usage-of-the-file-protocol-and-prefer-usage-of-custom-protocols%5D(https://www.electronjs.org/docs/latest/tutorial/security%2318-avoid-usage-of-the-file-protocol-and-prefer-usage-of-custom-protocols)&authuser=1). Consequently, our app runs on a custom protocol (e.g., blinkdiskapp://), not http or https, for both the frontend and backend. The recent change in [PR #5902](https://github.com/better-auth/better-auth/pull/5902) introduced strict validation that assumes a web-only environment. This breaks compatibility with secure Electron setups where the baseURL is using a custom scheme. We need a way to bypass this check or have the validator accept custom schemes to maintain security standards without breaking authentication.
GiteaMirror added the bug label 2026-03-13 10:11:23 -05:00
GiteaMirror commented 2026-03-13 10:11:24 -05:00
Author
Owner
Copy Link

@better-auth-agent[bot] commented on GitHub (Jan 6, 2026):

It seems that the current validation logic for the baseURL strictly requires http or https protocols, which indeed causes issues for Electron applications using custom protocols like app:// or blinkdisk://. This was introduced in a recent code change and has resulted in errors when initializing Better Auth in such contexts.

To address this, you have a couple of potential options:

  1. Open an Issue or Feature Request: Since this has been identified as a limitation, consider creating an issue to request support for custom protocols in the Better Auth framework, explaining your use case and why it's necessary.

  2. Look for Updates: Stay updated on any related discussions in the Better Auth library regarding this issue. There may be future updates or a configurable option that allows for flexibility in protocol validation.

Currently, you could explore alternative authentication options or configurations that could be compatible with your Electron setup while maintaining security best practices as you mentioned.

Would you like more information on any specific facets of implementing Better Auth in an Electron app, or assistance with a different aspect?

If you need more help, tag @better-auth-agent in a comment so I can respond.

Diagram • Discord • GitHub

Diagram Join Star

@better-auth-agent[bot] commented on GitHub (Jan 6, 2026): It seems that the current validation logic for the `baseURL` strictly requires `http` or `https` protocols, which indeed causes issues for Electron applications using custom protocols like `app://` or `blinkdisk://`. This was introduced in a recent code change and has resulted in errors when initializing Better Auth in such contexts. To address this, you have a couple of potential options: 1. **Open an Issue or Feature Request:** Since this has been identified as a limitation, consider creating an issue to request support for custom protocols in the Better Auth framework, explaining your use case and why it's necessary. 2. **Look for Updates:** Stay updated on any related discussions in the Better Auth library regarding this issue. There may be future updates or a configurable option that allows for flexibility in protocol validation. Currently, you could explore alternative authentication options or configurations that could be compatible with your Electron setup while maintaining security best practices as you mentioned. Would you like more information on any specific facets of implementing Better Auth in an Electron app, or assistance with a different aspect? _If you need more help, tag @better-auth-agent in a comment so I can respond._ <!-- bot:webhook reply v1 --> [Diagram](https://repodiagrams.s3.eu-north-1.amazonaws.com/skyvern_ultra_detailed_interactive.html) • [Discord](https://discord.gg/fG2XXEuQX3) • [GitHub](https://github.com/Skyvern-AI/Skyvern) [![Diagram](https://img.shields.io/badge/Diagram-2b3137?style=flat-square)](https://repodiagrams.s3.eu-north-1.amazonaws.com/skyvern_ultra_detailed_interactive.html) [![Join](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&style=flat-square)](https://discord.gg/fG2XXEuQX3) [![Star](https://img.shields.io/badge/star-181717?logo=github&logoColor=white&style=flat-square)](https://github.com/Skyvern-AI/Skyvern)
GiteaMirror commented 2026-03-13 10:11:26 -05:00
Author
Owner
Copy Link

@dosubot[bot] commented on GitHub (Jan 6, 2026):

The strict baseURL validation in Better Auth (since v1.4.10, PR #5902) enforces that only URLs with http or https protocols are accepted. This is implemented in the assertHasProtocol function, which throws an error if the protocol is not http or https, regardless of where the baseURL is set—config, environment, or runtime detection. As a result, custom protocols like app:// or electronapp:// are always rejected, breaking compatibility with Electron apps that follow security best practices by using custom schemes instead of file:// or http(s):// see code PR #5902.

There is currently no official configuration option or documented workaround to relax or bypass this protocol check for desktop environments. Some users have discussed custom plugins or forking as workarounds, but these are unofficial and not supported by the library see discussion.

Electron's security guidelines recommend using custom protocols to avoid the risks associated with file://, so this strict validation blocks secure, standards-compliant Electron setups.

A safe approach would be to allow developers to opt-in to custom protocols (e.g., via an allow-list or environment flag), or to provide an explicit override for trusted desktop environments. Until such a feature is added, supporting Electron custom protocols will require patching the library or maintaining a fork.

If you need a temporary workaround and are comfortable with advanced patching, you could monkey-patch the assertHasProtocol function at runtime to allow your custom protocol, but this comes with maintenance and security caveats.

To reply, just mention @dosu.

How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other

Chat with Dosu Open in Cursor Join Discord Share on X

@dosubot[bot] commented on GitHub (Jan 6, 2026): <!-- Answer --> The strict baseURL validation in Better Auth (since v1.4.10, PR #5902) enforces that only URLs with http or https protocols are accepted. This is implemented in the assertHasProtocol function, which throws an error if the protocol is not http or https, regardless of where the baseURL is set—config, environment, or runtime detection. As a result, custom protocols like app:// or electronapp:// are always rejected, breaking compatibility with Electron apps that follow security best practices by using custom schemes instead of file:// or http(s):// [see code](https://github.com/better-auth/better-auth/blob/c31c92f3d24f3ccfb6776d4634e0681c6dee2db5/packages/better-auth/src/utils/url.ts#L16-L156) [PR #5902](https://github.com/better-auth/better-auth/pull/5902). There is currently no official configuration option or documented workaround to relax or bypass this protocol check for desktop environments. Some users have discussed custom plugins or forking as workarounds, but these are unofficial and not supported by the library [see discussion](https://github.com/better-auth/better-auth/issues/783#issuecomment-3009401352). Electron's security guidelines recommend using custom protocols to avoid the risks associated with file://, so this strict validation blocks secure, standards-compliant Electron setups. A safe approach would be to allow developers to opt-in to custom protocols (e.g., via an allow-list or environment flag), or to provide an explicit override for trusted desktop environments. Until such a feature is added, supporting Electron custom protocols will require patching the library or maintaining a fork. If you need a temporary workaround and are comfortable with advanced patching, you could monkey-patch the assertHasProtocol function at runtime to allow your custom protocol, but this comes with maintenance and security caveats. <!-- Dosu Comment Footer --> *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- <sup>How did I do? [Good](https://app.dosu.dev/response-feedback/ddfa4988-35c0-44bd-86e1-b4d6638883c3?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/ddfa4988-35c0-44bd-86e1-b4d6638883c3?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/ddfa4988-35c0-44bd-86e1-b4d6638883c3?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/ddfa4988-35c0-44bd-86e1-b4d6638883c3?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/ddfa4988-35c0-44bd-86e1-b4d6638883c3?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/ddfa4988-35c0-44bd-86e1-b4d6638883c3?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/ddfa4988-35c0-44bd-86e1-b4d6638883c3?feedback_type=other)</sup> [![Chat with Dosu](https://dosu.dev/dosu-chat-badge.svg)](https://app.dosu.dev/cdda13d9-dd27-4d31-b09a-5d8bec92de21/ask?utm_source=github)&nbsp;[![Open in Cursor](https://dosu.dev/dosu-in-cursor.svg)](https://cursor.com/link/prompt?text=The%20strict%20baseURL%20validation%20in%20Better%20Auth%20%28since%20v1.4.10%2C%20PR%20%235902%29%20enforces%20that%20only%20URLs%20with%20http%20or%20https%20protocols%20are%20accepted.%20This%20is%20implemented%20in%20the%20assertHasProtocol%20function%2C%20which%20throws%20an%20error%20if%20the%20protocol%20is%20not%20http%20or%20https%2C%20regardless%20of%20where%20the%20baseURL%20is%20set%E2%80%94config%2C%20environment%2C%20or%20runtime%20detection.%20As%20a%20result%2C%20custom%20protocols%20like%20app%3A//%20or%20electronapp%3A//%20are%20always%20rejected%2C%20breaking%20compatibility%20with%20Electron%20apps%20that%20follow%20security%20best%20practices%20by%20using%20custom%20schemes%20instead%20of%20file%3A//%20or%20http%28s%29%3A//%20%5Bsee%20code%5D%28https%3A//github.com/better-auth/better-auth/blob/c31c92f3d24f3ccfb6776d4634e0681c6dee2db5/packages/better-auth/src/utils/url.ts%23L16-L156%29%20%5BPR%20%235902%5D%28https%3A//github.com/better-auth/better-auth/pull/5902%29.%0A%0AThere%20is%20currently%20no%20official%20configuration%20option%20or%20documented%20workaround%20to%20relax%20or%20bypass%20this%20protocol%20check%20for%20desktop%20environments.%20Some%20users%20have%20discussed%20custom%20plugins%20or%20forking%20as%20workarounds%2C%20but%20these%20are%20unofficial%20and%20not%20supported%20by%20the%20library%20%5Bsee%20discussion%5D%28https%3A//github.com/better-auth/better-auth/issues/783%23issuecomment-3009401352%29.%0A%0AElectron%27s%20security%20guidelines%20recommend%20using%20custom%20protocols%20to%20avoid%20the%20risks%20associated%20with%20file%3A//%2C%20so%20this%20strict%20validation%20blocks%20secure%2C%20standards-compliant%20Electron%20setups.%0A%0AA%20safe%20approach%20would%20be%20to%20allow%20developers%20to%20opt-in%20to%20custom%20protocols%20%28e.g.%2C%20via%20an%20allow-list%20or%20environment%20flag%29%2C%20or%20to%20provide%20an%20explicit%20override%20for%20trusted%20desktop%20environments.%20Until%20such%20a%20feature%20is%20added%2C%20supporting%20Electron%20custom%20protocols%20will%20require%20patching%20the%20library%20or%20maintaining%20a%20fork.%0A%0AIf%20you%20need%20a%20temporary%20workaround%20and%20are%20comfortable%20with%20advanced%20patching%2C%20you%20could%20monkey-patch%20the%20assertHasProtocol%20function%20at%20runtime%20to%20allow%20your%20custom%20protocol%2C%20but%20this%20comes%20with%20maintenance%20and%20security%20caveats.)&nbsp;[![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot)&nbsp;[![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/better-auth/better-auth/issues/7149)
GiteaMirror commented 2026-03-13 10:11:26 -05:00
Author
Owner
Copy Link

@bytaesu commented on GitHub (Jan 7, 2026):

Hi @poeck,

I'm thinking about this 🤓

@bytaesu commented on GitHub (Jan 7, 2026): Hi @poeck, I'm thinking about this 🤓
GiteaMirror commented 2026-03-13 10:11:27 -05:00
Author
Owner
Copy Link

@bytaesu commented on GitHub (Jan 7, 2026):

Hi @poeck,

baseURL should point to the Better Auth server instance. On that server instacne, set trustedOrigins to allow requests from your Electron app. Custom protocols are also supported!

cc @jslno

@bytaesu commented on GitHub (Jan 7, 2026): Hi @poeck, `baseURL` should point to the Better Auth server instance. On that server instacne, set `trustedOrigins` to allow requests from your Electron app. Custom protocols are also supported! cc @jslno
GiteaMirror commented 2026-03-13 10:11:27 -05:00
Author
Owner
Copy Link

@poeck commented on GitHub (Jan 7, 2026):

baseURL should point to the Better Auth server instance. On that server instacne, set trustedOrigins to allow requests from your Electron app. Custom protocols are also supported!

I am actually using a custom protocol to serve both the frontend and to "proxy" requests to the API (which also runs Better Auth).

In my example, all requests to blinkdiskapp://api are forwarded to my API, and Better Auth runs under the /api/auth base path.

You can find the code for the protocol proxy here: ebd7e8d8be/apps/electron/src/protocol.ts (L46)

And the auth client config here: ebd7e8d8be/apps/desktop/src/lib/auth.ts

@poeck commented on GitHub (Jan 7, 2026): > `baseURL` should point to the Better Auth server instance. On that server instacne, set `trustedOrigins` to allow requests from your Electron app. Custom protocols are also supported! I am actually using a custom protocol to serve both the frontend and to "proxy" requests to the API (which also runs Better Auth). In my example, all requests to `blinkdiskapp://api` are forwarded to my API, and Better Auth runs under the `/api/auth` base path. You can find the code for the protocol proxy here: https://github.com/blinkdisk/blinkdisk/blob/ebd7e8d8beb0854f1abdd60b27a53b5839e464e3/apps/electron/src/protocol.ts#L46 And the auth client config here: https://github.com/blinkdisk/blinkdisk/blob/ebd7e8d8beb0854f1abdd60b27a53b5839e464e3/apps/desktop/src/lib/auth.ts
GiteaMirror commented 2026-03-13 10:11:28 -05:00
Author
Owner
Copy Link

@dancomanlive commented on GitHub (Feb 24, 2026):

Why is this issue not fixed already?!

@dancomanlive commented on GitHub (Feb 24, 2026): Why is this issue not fixed already?!
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
adapter
astro
awaiting external contributor
blocked
breaking
breaking change
bug
c-devops
core
credentials
database
dependencies
devops
devtools
docs
documentation
duplicate
elysia
enhancement
enterprise
expo
express
fastify
good first issue
help wanted
hono
identity
infra
integration
invalid
javascript
locked
maintenance
need-more-information
needs: info
needs: repro
nextjs
nuxt
oauth
organization
P0
payments
perf
platform
plugin
pull-request
Mirrored from GitHub Pull Request
 question
ready
regression
remix
security
social-provider
solid
stale
svelte
tanstack-start
tracking
version-bump
vue
wontfix
No Label bug
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/better-auth#2659
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?