Adds keychain availability checks for all platforms

.github/workflows/ci.yml

@@ -44,7 +44,7 @@ jobs:
 
       - name: Run cmake (Unix)
         if: runner.os != 'Windows'
-        run: cmake . -DBUILD_TESTS=yes -DCMAKE_BUILD_TYPE=Release
+        run: cmake . -DBUILD_TESTS=yes -DSIMULATE_FAILURES=yes -DCMAKE_BUILD_TYPE=Release
 
       - name: Run cmake (Windows)
         if: runner.os == 'Windows'
@@ -87,7 +87,7 @@ jobs:
         run: brew install gcovr
 
       - name: Run cmake
-        run: cmake . -DBUILD_TESTS=yes -DCODE_COVERAGE=yes -DCMAKE_BUILD_TYPE=Debug
+        run: cmake . -DBUILD_TESTS=yes -DCODE_COVERAGE=yes -DSIMULATE_FAILURES=yes -DCMAKE_BUILD_TYPE=Debug
 
       - name: Build and run tests (Linux)
         if: runner.os == 'Linux'

CMakeLists.txt

@@ -3,6 +3,7 @@ cmake_minimum_required(VERSION 3.12.4)
 project(keychain)
 
 option(BUILD_TESTS "Build tests for ${PROJECT_NAME}" OFF)
+option(SIMULATE_FAILURES "Enable simulated failures in tests for ${PROJECT_NAME}" OFF)
 
 add_library(${PROJECT_NAME})
 target_include_directories(${PROJECT_NAME}
@@ -88,4 +89,12 @@ install(TARGETS ${PROJECT_NAME}
 
 if (BUILD_TESTS)
     add_subdirectory("test")
+    if (SIMULATE_FAILURES)
+        target_compile_definitions(${PROJECT_NAME}
+                PRIVATE
+                -DSIMULATE_FAILURES=1)
+        target_compile_definitions(${PROJECT_NAME}-test
+                PRIVATE
+                -DSIMULATE_FAILURES=1)
+    endif ()
 endif ()

include/keychain/keychain.h

@@ -84,11 +84,25 @@ void setPassword(const std::string &package, const std::string &service,
 void deletePassword(const std::string &package, const std::string &service,
                     const std::string &user, Error &err);
 
+/*! \brief Check if the keychain is available
+ *
+ * This function checks whether the platform's credential store is available
+ * and functional. On Linux and macOS, this probes the underlying service
+ * (SecretService or Keychain Services). On Windows, Credential Manager is
+ * a built-in OS component that is always available, so this is a no-op
+ * that always returns true.
+ *
+ * \param err Output parameter communicating success or error details
+ * \return true if the credential store is available, false otherwise
+ */
+bool isAvailable(Error &err);
+
 enum class ErrorType {
     // update CATCH_REGISTER_ENUM in tests.cpp when changing this
     NoError = 0,
     GenericError,
     NotFound,
+    Unavailable,
     // OS-specific errors
     PasswordTooLong = 10, // Windows only
     AccessDenied,         // macOS only

src/keychain_linux.cpp

@@ -158,4 +158,33 @@ void deletePassword(const std::string &package, const std::string &service,
     }
 }
 
+bool isAvailable(Error &err) {
+    err = Error{};
+
+#ifdef SIMULATE_FAILURES
+    // TEST HOOK: Simulate failure to create SecretService
+    if (getenv("KEYCHAIN_TEST_SIMULATED_FAILURE")) {
+        err.type = ErrorType::Unavailable;
+        err.message = "Simulated failure: SecretService unavailable";
+        err.code = -1;
+        return false;
+    }
+#endif
+
+    GError *error = NULL;
+    SecretService *svc =
+        secret_service_get_sync((SecretServiceFlags)0, NULL, &error);
+
+    if (error != NULL || svc == NULL) {
+        err.type = ErrorType::Unavailable;
+        err.message = error ? error->message : "SecretService unavailable";
+        err.code = error ? error->code : -1;
+        if (error)
+            g_error_free(error);
+        return false;
+    }
+    g_object_unref(svc);
+    return true;
+}
+
 } // namespace keychain

src/keychain_mac.cpp

@@ -270,4 +270,49 @@ void deletePassword(const std::string &package, const std::string &service,
     updateError(err, SecItemDelete(query.get()));
 }
 
+bool isAvailable(Error &err) {
+    err = Error{};
+
+    auto query = createCFMutableDictionary(err);
+    if (!query) {
+        err.type = ErrorType::Unavailable;
+        err.message = "Failed to create query dictionary";
+        return false;
+    }
+
+    CFDictionaryAddValue(query.get(), kSecClass, kSecClassGenericPassword);
+
+    auto service =
+        createCFStringWithCString("keychain_availability_check_service", err);
+    auto account =
+        createCFStringWithCString("keychain_availability_check_account", err);
+    if (!service || !account) {
+        err.type = ErrorType::Unavailable;
+        err.message = "Failed to create service/account string";
+        return false;
+    }
+
+    CFDictionaryAddValue(query.get(), kSecAttrService, service.get());
+    CFDictionaryAddValue(query.get(), kSecAttrAccount, account.get());
+    CFDictionaryAddValue(query.get(), kSecReturnData, kCFBooleanFalse);
+
+#ifdef SIMULATE_FAILURES
+    // TEST HOOK: Simulate SecItemCopyMatching failure
+    if (getenv("KEYCHAIN_TEST_SIMULATED_FAILURE")) {
+        err.type = ErrorType::Unavailable;
+        err.message = "Simulated failure: SecItemCopyMatching";
+        return false;
+    }
+#endif
+
+    OSStatus status = SecItemCopyMatching(query.get(), nullptr);
+
+    if (status == errSecSuccess || status == errSecItemNotFound) {
+        return true;
+    } else {
+        err.type = ErrorType::Unavailable;
+        err.message = errorStatusToString(status);
+        return false;
+    }
+}
 } // namespace keychain

src/keychain_win.cpp

@@ -250,4 +250,11 @@ void deletePassword(const std::string &package, const std::string &service,
     }
 }
 
+bool isAvailable(Error &err) {
+    // Credential Manager is always present on Windows;
+    // any runtime errors will surface in get/set/delete.
+    err = Error{};
+    return true;
+}
+
 } // namespace keychain

test/tests.cpp

@@ -8,6 +8,7 @@ CATCH_REGISTER_ENUM(keychain::ErrorType,
                     keychain::ErrorType::NoError,
                     keychain::ErrorType::GenericError,
                     keychain::ErrorType::NotFound,
+                    keychain::ErrorType::Unavailable,
                     keychain::ErrorType::PasswordTooLong,
                     keychain::ErrorType::AccessDenied)
 // clang-format on
@@ -111,4 +112,38 @@ TEST_CASE("Keychain", "[keychain]") {
         deletePassword(package, service, user, ec);
         check_no_error(ec);
     }
+
+#if defined(KEYCHAIN_MACOS) && defined(SIMULATE_FAILURES)
+    SECTION("isAvailable fails at SecItemCopyMatching") {
+        setenv("KEYCHAIN_TEST_SIMULATED_FAILURE", "1", 1);
+        Error ec{};
+        bool available = isAvailable(ec);
+        CHECK_FALSE(available);
+        CHECK(ec.type == ErrorType::Unavailable);
+        CHECK(ec.message.find("Simulated failure: SecItemCopyMatching") !=
+              std::string::npos);
+        unsetenv("KEYCHAIN_TEST_SIMULATED_FAILURE");
+    }
+#endif
+
+#if defined(KEYCHAIN_LINUX) && defined(SIMULATE_FAILURES)
+    SECTION("isAvailable fails at SecretService creation") {
+        setenv("KEYCHAIN_TEST_SIMULATED_FAILURE", "1", 1);
+        Error ec{};
+        bool available = isAvailable(ec);
+        CHECK_FALSE(available);
+        CHECK(ec.type == ErrorType::Unavailable);
+        CHECK(ec.message.find("Simulated failure: SecretService unavailable") !=
+              std::string::npos);
+        unsetenv("KEYCHAIN_TEST_SIMULATED_FAILURE");
+    }
+#endif
+
+    SECTION("isAvailable returns true and no error on supported platforms") {
+        Error ec{};
+        bool available = isAvailable(ec);
+
+        REQUIRE(available);
+        check_no_error(ec);
+    }
 }