Suggestion for GitButler's secret storage and usage mechanisms

[nshcr]

Sorry for my recent streak of nitpicking about the token-related issues — I've been learning about security lately and tried to look at GitButler's secret storage and usage mechanisms from the perspective of a privacy- or security-conscious user doing a bit of reverse-engineering.

And well… that actually led me to a few interesting findings.

From what I can tell with my limited knowledge, GitButler's secret mechanism is already sufficiently secure and properly handled on the backend.

Most of the issues I've noticed are on the frontend (or usage) side (or maybe I'm just not skilled enough to spot backend ones). The way secrets are stored isn't necessarily a best practice — I mean, it's already good, but it could be made even more robust and future-proof instead of leaving potential weak spots behind.

Here are some of my thoughts and takeaways regarding secret handling:

1. Keychain or system-level secret storage should only store the secret itself — no extra data structures, and definitely not multiple tokens in a single keychain item.

In the new GitHub multi-account support feature, GitButler stores metadata together with tokens in the keychain for easier data restoration.

While convenient, this might set a precedent that encourages adding more metadata or complex structures later, which is generally not a good design direction. The keychain should focus purely on sensitive data — simple, minimal, and robust.

• Store the GH users in one secret #10679
• Store the GH access tokens under individual secrets #10747

2. (Already fixed — thank you for addressing it!) Secrets should never be stored directly in localStorage. Since they're already safely kept in the keychain, there's no need to add extra exposure risk.

• web app uses cookie #10767
• Store tokens in keychain #10776

3. GitButler account authorization tokens shouldn't rely on a long-lived, never-expiring UUID v4 token. A JWT + refresh token design would be ideal — it's a well-established standard approach.

• web profile: Ability to refresh the access token #10773

4. (Thanks to @Byron for pointing this out and fixing it!) Tokens entered for GitLab, OpenAI, Anthropic and similar integrations should be masked to some degree in the UI — and in logs as well. Tokens should never be printed or exposed.

• do not log secrets #10781
• Hide sensitive information in the UI #10782
• Hide sensitive information in secret input fields with password masking #10783

5. Be careful with cross-project or cross-app (stable, nightly, dev) key sharing.

The GitLab token issue first appeared as unwanted token duplication and reuse across multiple projects.

Similarly, OpenAI and Anthropic API keys in the keychain currently lack namespace prefixes, which allows different GitButler app variants (with distinct bundle IDs) to access them.

I mean, reusing the same keychain item across builds isn't inherently bad, but it does open a backdoor for modified apps to impersonate another and steal tokens.

Sure, a tampered app could always try to request unauthorized secrets — but if GitButler never requests secrets outside its intended scope, users are far more likely to notice if something suspicious happens.

• GitLab Forge's token incorrectly applied to other projects #10777

[Byron]

Thanks so much - we don't perceive this as nitpicking, but as a necessity to improve the application's security posture. Going from an MVP to a tool used by millions means we need to get this right.

First of all, let's use this as tracking issue, which is great to have.

Let me share my thoughts related a couple of points brought up here.

Keychain or system-level secret storage should only store the secret itself — no extra data structures, and definitely not multiple tokens in a single keychain item.

@estib-vega and I discussed this on Discord, with the the outcome that we will only store the secret itself, plainly, in their respective keychain items.

GitButler account authorization tokens shouldn't rely on a long-lived, never-expiring UUID v4 token. A JWT + refresh token design would be ideal — it's a well-established standard approach.

This was discussed yesterday, with the ability to cycle the secret as outcome. It's a decision that keeps the cost and complexity in check, in times where the GitButler account isn't all that important yet.
However, I hope we will migrate to something standard before we go v1.0 (#10785).

Be careful with cross-project or cross-app (stable, nightly, dev) key sharing.

@estib-vega and I discussed in the office that it's a better UX to stop sharing secrets between application, and avoid the password prompt simply by not sharing secrets between the builds.

Similarly, OpenAI and Anthropic API keys in the keychain currently lack namespace prefixes, which allows different GitButler app variants (with distinct bundle IDs) to access them.

I mean, reusing the same keychain item across builds isn't inherently bad, but it does open a backdoor for modified apps to impersonate another and steal tokens.

Sure, a tampered app could always try to request unauthorized secrets — but if GitButler never requests secrets outside its intended scope, users are far more likely to notice if something suspicious happens.

I think this is argument enough to not use global secrets anymore. The easiest way to achieve this is to retire secret_set_global() and turn it into a function that stores per application secrets instead. We should have a migration that moves existing global secrets into per-application ones. I have started this process here as PoC, without meaning to impose this as a solution: #10786 .

[estib-vega]

@nshcr Just as a quick answer, this is no nitpick and there's no need to apologize. This is highly appreciated and frankly is good to have you question all of this.

[estib-vega]

Similarly, OpenAI and Anthropic API keys in the keychain currently lack namespace prefixes, which allows different GitButler app variants (with distinct bundle IDs) to access them.

I mean, reusing the same keychain item across builds isn't inherently bad, but it does open a backdoor for modified apps to impersonate another and steal tokens.

Here are my thoughts on this:

The risks

Even if the secrets were not shared across builds, there's the same risk of impersonation.
And that's mitigated by the fact that the user always would need to enter their password and actively authorize access.

Sure, a tampered app could always try to request unauthorized secrets — but if GitButler never requests secrets outside its intended scope, users are far more likely to notice if something suspicious happens.

People will get access request prompts if:

• They use multiple app channels at the same time (low impact, that's mainly people developing the app)
• They use the app and the CLI, even if in the same channel

The DevEx

I think this is were the "biggest" impact is felt IMO.

If we have build-scoped secrets:

• We reduce the access request prompts
• We don't cross-pollute environments while developing

If we have global secrets

• We get more access request prompts but once we've allowed a given app, then we don't need to allow it again (unless it's the unsigned dev binaries)

Conclusion

• Users will get access request prompts regardless of whether the secrets are scoped or not
• Impersonation is a risk regardless of scoping
• The main difference would be the development experience

[estib-vega]

For the sake of implementing something re: forge credential secrets, I'll got for global secrets.

The justification is that it's going to be easier to go from global secrets to build-kind secrets if we so want, rather than having to consolidate multiple build-kind secrets to one global.

[nshcr]

@Byron Thanks for the reply!

I didn't realize there had already been so much discussion — it seems that most of the issues mentioned here have either been resolved or are already being addressed.

Since this issue has now been marked as a tracking issue, I might as well look through the existing issues to find any older, related ones that are still open and list them here together.

@estib-vega Thanks for the detailed explanation!

I'm actually not very familiar with how keychain access control works, but here's my current understanding:

1. A secret isn't strictly bound to an app, but the app that creates it is automatically granted read / write access.
2. Even for the same app, if its bundle ID, signature, or other identifiers change, access to keys it previously created will require reauthorization (it's treated as a different app for access control).
3. Even if multiple app binaries are distributed with the same signature, they're still treated as separate apps with independent access control.

So the main issue lies in point 2 — my earlier example using "impersonation" was mainly meant to simulate a specific edge case, though I now realize it wasn't an appropriate analogy.

My understanding is: if an app always only reads / writes keys it created itself, and it suddenly needs to request access authorization, that likely means:

1. The app's signature or bundle ID has changed unexpectedly, or
2. The keychain authorization for the app was revoked (by the system or the user).

In that situation, would it make more sense for the app to automatically refresh the secrets storage instead of trying to reauthorize access to the old one?

Because from both perspectives — the app's (a suspicious signature change) and the user's (manual or system-level revocation) — it seems safer not to continue accessing the old key.

Of course, this is just a thought. I realize this approach might be a bit over-engineered, since it would require adding a identifier to each key name for rebuilding later.

[estib-vega]

In that situation, would it make more sense for the app to automatically refresh the secrets storage instead of trying to reauthorize access to the old one?

Because from both perspectives — the app's (a suspicious signature change) and the user's (manual or system-level revocation) — it seems safer not to continue accessing the old key.

Hmm I don't quite follow what you mean here. By refresh you mean prompting the user to reauthorize to e.g. GitHub instead of asking them for access to the secret?

[nshcr]

Hmm I don't quite follow what you mean here. By refresh you mean prompting the user to reauthorize to e.g. GitHub instead of asking them for access to the secret?

Oh yes — my idea is to add a fixed ID to all secret keys (it can be generated when the secret service is initialized and remain unchanged afterward).

If an unexpected situation occurs, the app can simply refresh this ID, effectively creating an entirely new storage pool and discarding the old one.

[Byron]

I also strongly lean towards trying to prevent training users that asking for reauthorization is OK and expected. This is a solved problem if the build kinds, Nightly and Stable, use their own non-overlapping namespaces.

However, this doesn't solve the problem that the but binary is like an extension of the gitbutler-tauri binary and it should share its credentials.

But… assuming that there is no easy way to do this naturally with macOS, which I think there must be, the simple way for us to achieve that is to implement but within gitbutler-tauri and just have two modes. The binary can inspect its name and act differently, or something like that.

Of course, this would still go against the preference of Esteban which is to share secrets across build kinds, but at least when we spoke I truly believed I understood the opposite, the separating them is preferred also to have a way to try things with Nightly first without messing with data used in Stable as well.
But then I also understand that Nightly isn't used by many users at all, and that we don't have to optimse for this case. We could even inform the user during onboarding that they can expect these popups.

But independently of that, I think we can at least make sure that Stable users won't see these popups even when using but, but that's at most tangentially related.

[nshcr]

Now I'm starting to think this issue might have gotten a bit overthought… Let me try to summarize based on what @estib-vega and @Byron said:

1. For users who only use the stable build, reauthorization should never be required unless there's an unexpected signature change or revoked access.
2. For developers who use both stable, nightly, or even dev builds, they should already be aware that reauthorization might occasionally be necessary — and understand why.

From that, I think the following suggestions make sense:

1. For stable-only users, if a reauthorization prompt appears, it likely indicates something suspicious. In such cases, the best approach would be to discard the old secret storage and rebuild a new one, rather than prompting the user to reauthorize access.
2. For developers working with multiple build channels, isolating secret storage between builds helps prevent cross-environment interference, while sharing the same storage doesn't offer significant benefits beyond saving a bit of authentication effort.

So my suggested approach is this: GitButler should always use only the secrets created by the current build itself. When a read failure or reauthorization issue occurs, it should create a new storage instead of asking the user to reauthorize access with their password.

I understand this would cause the dev build to recreate secret storage on every rebuild, so we could simply add a feature flag to limit this behavior to production builds like stable and nightly. The dev build can maintain its own isolated secret storage.

As for the but CLI's secret authorization — sorry, I don't really have a good idea there.
My understanding is that it's mainly used from the command line and can run independently of the GUI, so maintaining a separate secret storage for it rather than sharing GUI secrets should be perfectly acceptable.

---

Edit:

That said, I should also admit that I haven't actually seen any application designed this way — so this idea might just be a result of my own inexperience and overthinking.

It feels a bit like building defenses against imaginary threats. I'll set this thought aside for now and leave the decision entirely up to you.

[Byron]

1. For users who only use the stable build, reauthorization should never be required unless there's an unexpected signature change or revoked access.
2. For developers who use both stable, nightly, or even dev builds, they should already be aware that reauthorization might occasionally be necessary — and understand why.

Yes, thanks for paraphrasing, I second that.

1. For stable-only users, if a reauthorization prompt appears, it likely indicates something suspicious. In such cases, the best approach would be to discard the old secret storage and rebuild a new one, rather than prompting the user to reauthorize access.

It doesn't look like we have control over whether or not we want to allow such a prompt. Maybe there is an API for that, but it would be out of scope to use it - we have to rely on what keyring provides for cross-platform secret store handling.

2. For developers working with multiple build channels, isolating secret storage between builds helps prevent cross-environment interference, while sharing the same storage doesn't offer significant benefits beyond saving a bit of authentication effort.

I will definitely try to understand where we land on this one because I am still a bit confused 😅.

As for the but CLI's secret authorization — sorry, I don't really have a good idea there.
My understanding is that it's mainly used from the command line and can run independently of the GUI, so maintaining a separate secret storage for it rather than sharing GUI secrets should be perfectly acceptable.

but isn't a different GitButler, just another way to invoke it. As such, I think it's crucial that it shares all state with the GUI application.
Fortunately, I really think it's possible to do. For development we can still compile a separate but binary which uses a non-keyring based secrets store anyway to workaround the re-auth popups. And for release, we can actually have one binary that can act as CLI and GUI at the same time, thus solving the re-auth problem 🎉.

[estib-vega]

I have a couple of questions:

• Why is it a bad think to ask for access to a secret? I happens only ever once per application, and is not need even after application updates (as long as they are signed)
• Is it worth moving but closer to the tauri crate for in order to bypass a prompt? I think that's a high price for a quality of life change.

Maybe I'm missing something here, but I'd like to keep but completely independent of the tauri-specific code, because in case we want to move away from it, we won't have to tear off but