fix: detect a selected-but-unusable OS keyring and fall back gracefully

[kundansable]

Summary

Fixes #10107 — in Desktop mode on Debian 13 (Trixie) under an RDP session (no D-Bus / GNOME Keyring available), pgAdmin fails with a bare CryptKeyMissing on every server-registration or connect attempt, instead of falling back to the master-password mechanism.

Root Cause

evaluate_and_patch_config() only disables USE_OS_SECRET_STORAGE when keyring.get_keyring().name == 'fail Keyring' — i.e. when the keyring library couldn't find any backend at all. On Debian 13 over RDP, a real backend (e.g. SecretService) is selected (so the name check passes), but it's non-functional because there's no D-Bus/GNOME Keyring session running in that environment. Every actual keyring read/write then fails silently at a different layer, the crypt key never gets set, and Connection.connect() unconditionally raises CryptKeyMissing whenever the key is absent — with no recovery path.

Fix

After a keyring backend is selected, probe it with a harmless read of a never-existing entry (keyring.get_password('pgAdmin4', 'entry_to_check_keyring_access')). A healthy backend returns None without prompting (OS keyrings only prompt for existing entries). An unusable backend raises an exception on this probe — in that case, disable USE_OS_SECRET_STORAGE so the app falls back to the master-password / in-app crypt key mechanism instead of failing outright.

Test Steps

(Requires a Debian 13 desktop-mode environment without a working D-Bus/keyring session — e.g. an RDP session, or simulate by disabling/blocking the keyring daemon.)

1. On an affected system, launch pgAdmin in Desktop mode and try to register a new server with "Save Password" checked.
2. Before the fix: operation fails with pgadmin.utils.exception.CryptKeyMissing.
3. After the fix: registration succeeds; pgAdmin instead prompts for/uses the master password mechanism, with no CryptKeyMissing error.
4. Regression: on a normal desktop environment where the OS keyring does work (e.g. macOS Keychain, or a working Linux session), confirm USE_OS_SECRET_STORAGE stays enabled and passwords are still stored via the OS keyring as before (no unnecessary fallback).
5. Confirm Server mode (Debian 13, browser access) is unaffected, per the original report.

Summary by CodeRabbit

• Bug Fixes
  • Improved detection of unavailable or unusable OS keyring providers.
  • Automatically disables OS secret storage and clears the keyring setting when the configured provider cannot be used.
  • Preserves the selected keyring configuration when availability is confirmed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d4d06f93-8f52-4a66-83d3-98164492c30d

📥 Commits

Reviewing files that changed from the base of the PR and between b15c745 and 705f125.

📒 Files selected for processing (1)

• web/pgadmin/evaluate_config.py

---

Walkthrough

The configuration now probes non-failing keyring backends before enabling OS secret storage. Probe failures disable OS secret storage and clear KEYRING_NAME; successful probes preserve the existing keyring configuration.

Changes

OS secret storage configuration

Layer / File(s)	Summary
Probe keyring before enabling secret storage web/pgadmin/evaluate_config.py	The configuration retains the 'fail Keyring' check, performs a harmless password lookup for other backends, and disables OS secret storage when the probe raises an exception.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: yogeshmahajan-1903

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main fix: detecting an unusable OS keyring and falling back gracefully.
Linked Issues check	✅ Passed	The change probes the selected keyring, disables OS secret storage on failure, and preserves working keyrings as required by #10107.
Out of Scope Changes check	✅ Passed	The patch stays focused on keyring usability detection and fallback behavior, with no unrelated changes apparent.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}