Add NegativeCacheHitException for negative cache detection

- Add NegativeCacheHitException class inheriting from InvalidIssuerException
- Add negative_cache_hits counter to IssuerStats for monitoring
- Detect negative cache entries in get_public_keys_from_db() and throw
  NegativeCacheHitException with descriptive message including the issuer
- Add negative_cache_hits field to monitoring JSON output
- Add NegativeCacheTest unit test that verifies:
  - Negative cache entries are created for invalid issuers
  - NegativeCacheHitException is thrown on subsequent access
  - negative_cache_hits counter increments correctly (only for hits, not misses)
  - Use unique issuer per test run to avoid interference from cache persistence

This allows callers to distinguish negative cache hits from other
validation failures and enables monitoring of negative cache effectiveness.

Author: bbockelm

src/scitokens_cache.cpp

@@ -209,6 +209,35 @@ bool scitokens::Validator::get_public_keys_from_db(const std::string issuer,
             return false;
         }
         auto keys_local = iter->second;
+
+        // Check if this is a negative cache entry (empty keys array)
+        if (keys_local.is<picojson::object>()) {
+            auto jwks_obj = keys_local.get<picojson::object>();
+            auto keys_iter = jwks_obj.find("keys");
+            if (keys_iter != jwks_obj.end() &&
+                keys_iter->second.is<picojson::array>()) {
+                auto keys_array = keys_iter->second.get<picojson::array>();
+                if (keys_array.empty()) {
+                    // Check if negative cache has expired
+                    iter = top_obj.find("expires");
+                    if (iter != top_obj.end() && iter->second.is<int64_t>()) {
+                        auto expiry = iter->second.get<int64_t>();
+                        if (now > expiry) {
+                            // Negative cache expired, remove and return false
+                            if (remove_issuer_entry(db, issuer, true) != 0) {
+                                return false;
+                            }
+                            sqlite3_close(db);
+                            return false;
+                        }
+                    }
+                    // Negative cache still valid - throw exception
+                    sqlite3_close(db);
+                    throw NegativeCacheHitException(issuer);
+                }
+            }
+        }
+
         iter = top_obj.find("expires");
         if (iter == top_obj.end() || !iter->second.is<int64_t>()) {
             if (remove_issuer_entry(db, issuer, true) != 0) {

src/scitokens_internal.cpp

@@ -921,8 +921,14 @@ std::string Validator::get_jwks(const std::string &issuer) {
     auto now = std::time(NULL);
     picojson::value jwks;
     int64_t next_update;
-    if (get_public_keys_from_db(issuer, now, jwks, next_update)) {
-        return jwks.serialize();
+    try {
+        if (get_public_keys_from_db(issuer, now, jwks, next_update)) {
+            return jwks.serialize();
+        }
+    } catch (const NegativeCacheHitException &) {
+        // Negative cache hit - return empty keys without incrementing counter
+        // (counter is incremented elsewhere for validation failures)
+        return std::string("{\"keys\": []}");
     }
     return std::string("{\"keys\": []}");
 }

src/scitokens_internal.h

@@ -264,6 +264,9 @@ struct IssuerStats {
     std::atomic<uint64_t> background_successful_refreshes{0};
     std::atomic<uint64_t> background_failed_refreshes{0};
 
+    // Negative cache statistics
+    std::atomic<uint64_t> negative_cache_hits{0};
+
     // Increment methods for atomic counters (use relaxed ordering for stats)
     void inc_successful_validation() {
         successful_validations.fetch_add(1, std::memory_order_relaxed);
@@ -301,6 +304,9 @@ struct IssuerStats {
     void inc_background_failed_refresh() {
         background_failed_refreshes.fetch_add(1, std::memory_order_relaxed);
     }
+    void inc_negative_cache_hit() {
+        negative_cache_hits.fetch_add(1, std::memory_order_relaxed);
+    }
 
     // Time setters that accept std::chrono::duration (use relaxed ordering)
     template <typename Rep, typename Period>
@@ -476,6 +482,14 @@ class InvalidIssuerException : public std::runtime_error {
     InvalidIssuerException(const std::string &msg) : std::runtime_error(msg) {}
 };
 
+class NegativeCacheHitException : public InvalidIssuerException {
+  public:
+    explicit NegativeCacheHitException(const std::string &issuer)
+        : InvalidIssuerException("Issuer is in negative cache (recently failed "
+                                 "to retrieve keys): " +
+                                 issuer) {}
+};
+
 class JsonException : public std::runtime_error {
   public:
     JsonException(const std::string &msg) : std::runtime_error(msg) {}
@@ -1350,6 +1364,8 @@ class Validator {
                                        const std::exception &e) {
         if (dynamic_cast<const TokenExpiredException *>(&e)) {
             stats.inc_expired_token();
+        } else if (dynamic_cast<const NegativeCacheHitException *>(&e)) {
+            stats.inc_negative_cache_hit();
         }
 
         stats.inc_unsuccessful_validation();

src/scitokens_monitoring.cpp

@@ -134,6 +134,11 @@ std::string MonitoringStats::get_json() const {
             static_cast<int64_t>(stats.background_failed_refreshes.load(
                 std::memory_order_relaxed)));
 
+        // Negative cache statistics
+        issuer_obj["negative_cache_hits"] =
+            picojson::value(static_cast<int64_t>(
+                stats.negative_cache_hits.load(std::memory_order_relaxed)));
+
         std::string sanitized_issuer = sanitize_issuer_for_json(issuer);
         issuers_obj[sanitized_issuer] = picojson::value(issuer_obj);
     }

test/main.cpp

@@ -843,6 +843,109 @@ TEST_F(KeycacheTest, RefreshExpiredTest) {
     EXPECT_EQ(jwks_str, "{\"keys\": []}");
 }
 
+TEST_F(KeycacheTest, NegativeCacheTest) {
+    // This test verifies that failed issuer lookups are cached as negative
+    // entries and that subsequent attempts fail quickly with the right counter
+    char *err_msg = nullptr;
+
+    // Reset monitoring stats for clean baseline
+    scitoken_reset_monitoring_stats(&err_msg);
+    if (err_msg) {
+        free(err_msg);
+        err_msg = nullptr;
+    }
+
+    // Create a token with an issuer that will fail to lookup
+    std::unique_ptr<void, decltype(&scitoken_key_destroy)> mykey(
+        scitoken_key_create("1", "ES256", ec_public, ec_private, &err_msg),
+        scitoken_key_destroy);
+    ASSERT_TRUE(mykey.get() != nullptr) << err_msg;
+
+    std::unique_ptr<void, decltype(&scitoken_destroy)> mytoken(
+        scitoken_create(mykey.get()), scitoken_destroy);
+    ASSERT_TRUE(mytoken.get() != nullptr);
+
+    // Use a unique issuer that doesn't exist (will fail to fetch keys)
+    // Include timestamp to avoid interference from previous test runs
+    std::string invalid_issuer = "https://invalid-issuer-negative-cache-" +
+                                 std::to_string(std::time(nullptr)) +
+                                 ".example.com";
+    auto rv = scitoken_set_claim_string(mytoken.get(), "iss",
+                                        invalid_issuer.c_str(), &err_msg);
+    ASSERT_TRUE(rv == 0) << err_msg;
+
+    char *token_value = nullptr;
+    rv = scitoken_serialize(mytoken.get(), &token_value, &err_msg);
+    ASSERT_TRUE(rv == 0) << err_msg;
+    std::unique_ptr<char, decltype(&free)> token_value_ptr(token_value, free);
+
+    // First attempt should fail to fetch keys (DNS failure or connection
+    // refused). This is a cache MISS (creates negative cache entry).
+    std::unique_ptr<void, decltype(&scitoken_destroy)> read_token(
+        scitoken_create(nullptr), scitoken_destroy);
+    ASSERT_TRUE(read_token.get() != nullptr);
+
+    rv = scitoken_deserialize_v2(token_value, read_token.get(), nullptr,
+                                 &err_msg);
+    ASSERT_FALSE(rv == 0); // Should fail
+    if (err_msg) {
+        free(err_msg);
+        err_msg = nullptr;
+    }
+
+    // Check that a negative cache entry was created (returns empty keys)
+    char *jwks;
+    rv = keycache_get_cached_jwks(invalid_issuer.c_str(), &jwks, &err_msg);
+    ASSERT_TRUE(rv == 0) << err_msg;
+    ASSERT_TRUE(jwks != nullptr);
+    std::string jwks_str(jwks);
+    free(jwks);
+
+    // Should return empty keys array (negative cache)
+    EXPECT_EQ(jwks_str, "{\"keys\": []}");
+
+    // Second attempt should fail quickly using negative cache
+    rv = scitoken_deserialize_v2(token_value, read_token.get(), nullptr,
+                                 &err_msg);
+    ASSERT_FALSE(rv == 0); // Should still fail
+    ASSERT_TRUE(err_msg != nullptr);
+    std::string error_msg(err_msg);
+    free(err_msg);
+    err_msg = nullptr;
+
+    // Error message should indicate it's from negative cache
+    EXPECT_NE(error_msg.find("negative cache"), std::string::npos)
+        << "Error message should mention negative cache: " << error_msg;
+
+    // Third attempt to verify counter increments correctly
+    rv = scitoken_deserialize_v2(token_value, read_token.get(), nullptr,
+                                 &err_msg);
+    ASSERT_FALSE(rv == 0);
+    if (err_msg) {
+        free(err_msg);
+        err_msg = nullptr;
+    }
+
+    // Get monitoring stats and verify negative_cache_hits counter
+    char *json_out = nullptr;
+    rv = scitoken_get_monitoring_json(&json_out, &err_msg);
+    ASSERT_TRUE(rv == 0) << err_msg;
+    ASSERT_TRUE(json_out != nullptr);
+    std::string json_str(json_out);
+    free(json_out);
+
+    // Parse JSON and check negative_cache_hits
+    // Only the second and third attempts should hit the negative cache:
+    // - First attempt: creates negative cache (cache miss, not hit)
+    // - Second and third attempts: hit existing negative cache
+    EXPECT_NE(json_str.find("\"negative_cache_hits\""), std::string::npos)
+        << "JSON should contain negative_cache_hits field";
+
+    // Verify 2 negative cache hits (attempts 2 and 3 only)
+    EXPECT_NE(json_str.find("\"negative_cache_hits\":2"), std::string::npos)
+        << "Should have 2 negative cache hits. JSON: " << json_str;
+}
+
 class IssuerSecurityTest : public ::testing::Test {
   protected:
     void SetUp() override {