docs: record that libsecret is validated against GNOME Keyring only

CHANGELOG.md

@@ -9,6 +9,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **The libsecret backend is now documented as GNOME Keyring only** (#19). It was described
+  as working with "GNOME Keyring, KWallet's shim, any Secret Service implementation", which
+  testing disproved. KWallet's shim (`ksecretd`) fails unattended in two distinct ways: it does
+  not provide the `session` collection GNOME Keyring offers, so selecting it fails with
+  *"No such object path `/org/freedesktop/secrets/aliases/session`"*; and against the default
+  collection it raises a wallet-unlock prompt which, with no GUI, blocks the caller forever.
+  The README and the XML docs now say what is actually validated, and `KeyringCollection`
+  notes that `"session"` is a GNOME convenience rather than a portable value. Documentation
+  only — no behaviour change. The blocking-call defect the validation surfaced is tracked
+  separately in #74.
+
 ### Fixed
 
 - **The Keychain backend could see another CLI's credentials** (#55). App scoping was a

README.md

@@ -304,9 +304,22 @@ services.AddCredentialStore(opts =>
 
 > ⚠️ **Experimental.** Requires a running Secret Service daemon — headless
 > containers and SSH-only servers typically don't have one, and operations
-> will throw with a clear message. Primarily validated against GNOME
-> Keyring on Ubuntu. `UseKeyring = true` on non-Linux platforms throws
-> `PlatformNotSupportedException` at registration time.
+> will throw with a clear message. `UseKeyring = true` on non-Linux platforms
+> throws `PlatformNotSupportedException` at registration time.
+
+**Validated against GNOME Keyring only.** KWallet's Secret Service shim
+(`ksecretd`) was tested and does *not* work unattended (see
+[#19](https://github.com/StuartMeeks/NextIteration.SpectreConsole.Auth/issues/19)):
+
+- It does not provide the `session` collection that GNOME Keyring does, so
+  `KeyringCollection = "session"` fails outright with *"No such object path
+  `/org/freedesktop/secrets/aliases/session`"*.
+- With the default collection it prompts to unlock the wallet. In a desktop KDE
+  session a user can answer that; with no GUI the call **blocks indefinitely**,
+  because libsecret's synchronous API is invoked without a cancellable.
+
+Treat KWallet as unsupported until that is addressed. Other Secret Service
+implementations are untested.
 
 `UseKeyring` and `UseKeychain` are mutually exclusive — setting both throws.
 The file-based backend remains the default when neither is set.
@@ -373,7 +386,7 @@ Everything else is transitive.
 
 ## Contributing
 
-Issues and PRs welcome. Outstanding hardening is tracked in [GitHub issues](https://github.com/StuartMeeks/NextIteration.SpectreConsole.Auth/issues) — currently KWallet validation for the libsecret backend ([#19](https://github.com/StuartMeeks/NextIteration.SpectreConsole.Auth/issues/19)).
+Issues and PRs welcome. Outstanding hardening is tracked in [GitHub issues](https://github.com/StuartMeeks/NextIteration.SpectreConsole.Auth/issues) — currently the libsecret backend blocking on a Secret Service prompt ([#74](https://github.com/StuartMeeks/NextIteration.SpectreConsole.Auth/issues/74)).
 
 When contributing code, please keep the zero-warning, fully-documented public surface. `TreatWarningsAsErrors` is on for a reason.
 

src/NextIteration.SpectreConsole.Auth/CredentialStoreOptions.cs

@@ -59,10 +59,11 @@ public sealed class CredentialStoreOptions
         /// registration.
         /// </summary>
         /// <remarks>
-        /// The libsecret backend is marked <b>experimental</b>. Requires a
-        /// running Secret Service (GNOME Keyring, KWallet's shim, etc.);
-        /// headless containers typically lack one and registration will
-        /// surface a clear error.
+        /// The libsecret backend is marked <b>experimental</b> and is validated
+        /// against GNOME Keyring only — KWallet's shim was tested and does not work
+        /// unattended (see the remarks on <c>LibsecretCredentialManager</c>). Requires a
+        /// running Secret Service; headless containers typically lack one and
+        /// registration will surface a clear error.
         /// </remarks>
         public bool UseKeyring { get; set; }
 
@@ -76,6 +77,11 @@ public sealed class CredentialStoreOptions
         /// <summary>
         /// Secret Service collection that stored items are written to.
         /// Defaults to <c>"default"</c> (usually the user's login keyring).
+        /// <para>
+        /// Note that <c>"session"</c> is a GNOME Keyring convenience and is not
+        /// universal: KWallet's shim does not provide it, so a value that works under
+        /// one Secret Service implementation may not under another (#19).
+        /// </para>
         /// Set to <c>"session"</c> for the in-memory session keyring that
         /// always exists on a running Secret Service daemon — useful for
         /// CI environments where the login keyring has not been

src/NextIteration.SpectreConsole.Auth/Persistence/Libsecret/LibsecretCredentialManager.cs

@@ -9,14 +9,22 @@ namespace NextIteration.SpectreConsole.Auth.Persistence.Libsecret
     /// <summary>
     /// <see cref="ICredentialManager"/> implementation backed by the Secret
     /// Service API (libsecret). Each credential becomes a libsecret item in
-    /// the user's default keyring (GNOME Keyring, KWallet's shim, etc.).
+    /// the user's default keyring.
     /// </summary>
     /// <remarks>
     /// <para>
-    /// This backend is marked <b>experimental</b>. Tested against
-    /// <c>gnome-keyring-daemon</c> on Ubuntu; behaviour on other Secret
-    /// Service implementations (KWallet, <c>kwallet-secrets</c>, or the
-    /// <c>pass</c> shim) has not been verified.
+    /// This backend is marked <b>experimental</b> and is validated against
+    /// <c>gnome-keyring-daemon</c> only.
+    /// </para>
+    /// <para>
+    /// <b>KWallet is not supported.</b> Its Secret Service shim (<c>ksecretd</c>) was
+    /// tested and fails unattended in two ways (#19): it does not provide the
+    /// <c>session</c> collection GNOME Keyring offers, so selecting it fails with
+    /// <c>No such object path '/org/freedesktop/secrets/aliases/session'</c>; and against
+    /// the default collection it raises a wallet-unlock prompt, which with no GUI blocks
+    /// the calling thread forever because the synchronous libsecret entry points here are
+    /// invoked with a NULL <c>GCancellable</c>. Other Secret Service implementations are
+    /// untested.
     /// </para>
     /// <para>
     /// Requires a running Secret Service daemon. Headless containers and