Add keycache load, metadata, and delete APIs with tests

Copilot · bbockelm · Copilot · commit 44c06f56da31 · 2025-12-11T20:29:42.000Z
Co-authored-by: bbockelm &lt;1093447+bbockelm@users.noreply.github.com&gt;
diff --git a/src/scitokens.cpp b/src/scitokens.cpp
@@ -1134,6 +1134,78 @@ int keycache_stop_background_refresh(char **err_msg) {
     return keycache_set_background_refresh(0, err_msg);
 }
 
+int keycache_load_jwks(const char *issuer, char **jwks, char **err_msg) {
+    if (!issuer) {
+        if (err_msg) {
+            *err_msg = strdup("Issuer may not be a null pointer");
+        }
+        return -1;
+    }
+    if (!jwks) {
+        if (err_msg) {
+            *err_msg = strdup("JWKS output pointer may not be null.");
+        }
+        return -1;
+    }
+    try {
+        *jwks = strdup(scitokens::Validator::load_jwks(issuer).c_str());
+    } catch (std::exception &exc) {
+        if (err_msg) {
+            *err_msg = strdup(exc.what());
+        }
+        return -1;
+    }
+    return 0;
+}
+
+int keycache_get_jwks_metadata(const char *issuer, char **metadata,
+                               char **err_msg) {
+    if (!issuer) {
+        if (err_msg) {
+            *err_msg = strdup("Issuer may not be a null pointer");
+        }
+        return -1;
+    }
+    if (!metadata) {
+        if (err_msg) {
+            *err_msg = strdup("Metadata output pointer may not be null.");
+        }
+        return -1;
+    }
+    try {
+        *metadata = strdup(scitokens::Validator::get_jwks_metadata(issuer).c_str());
+    } catch (std::exception &exc) {
+        if (err_msg) {
+            *err_msg = strdup(exc.what());
+        }
+        return -1;
+    }
+    return 0;
+}
+
+int keycache_delete_jwks(const char *issuer, char **err_msg) {
+    if (!issuer) {
+        if (err_msg) {
+            *err_msg = strdup("Issuer may not be a null pointer");
+        }
+        return -1;
+    }
+    try {
+        if (!scitokens::Validator::delete_jwks(issuer)) {
+            if (err_msg) {
+                *err_msg = strdup("Failed to delete JWKS cache entry for issuer.");
+            }
+            return -1;
+        }
+    } catch (std::exception &exc) {
+        if (err_msg) {
+            *err_msg = strdup(exc.what());
+        }
+        return -1;
+    }
+    return 0;
+}
+
 int config_set_int(const char *key, int value, char **err_msg) {
     return scitoken_config_set_int(key, value, err_msg);
 }
diff --git a/src/scitokens.h b/src/scitokens.h
@@ -309,6 +309,36 @@ int keycache_set_background_refresh(int enabled, char **err_msg);
  */
 int keycache_stop_background_refresh(char **err_msg);
 
+/**
+ * Load the JWKS from the keycache for a given issuer, refreshing only if needed.
+ * - Returns 0 if successful, nonzero on failure.
+ * - If the existing JWKS has not expired, this will return the cached JWKS
+ *   without triggering a download.
+ * - If the JWKS has expired or does not exist, this will attempt to refresh
+ *   it from the issuer.
+ * - `jwks` is an output variable set to the contents of the JWKS.
+ */
+int keycache_load_jwks(const char *issuer, char **jwks, char **err_msg);
+
+/**
+ * Get metadata for a cached JWKS entry.
+ * - Returns 0 if successful, nonzero on failure.
+ * - `metadata` is an output variable set to a JSON string containing:
+ *   - "expires": expiration time (Unix epoch seconds)
+ *   - "next_update": next update time (Unix epoch seconds)
+ *   - "extra": additional metadata (currently an empty JSON object)
+ * - If the issuer does not exist in the cache, returns an error.
+ */
+int keycache_get_jwks_metadata(const char *issuer, char **metadata,
+                               char **err_msg);
+
+/**
+ * Delete a JWKS entry from the keycache.
+ * - Returns 0 if successful, nonzero on failure.
+ * - If the issuer does not exist in the cache, this is not considered an error.
+ */
+int keycache_delete_jwks(const char *issuer, char **err_msg);
+
 /**
  * APIs for managing scitokens configuration parameters.
  */
diff --git a/src/scitokens_cache.cpp b/src/scitokens_cache.cpp
@@ -425,3 +425,133 @@ scitokens::Validator::get_all_issuers_from_db(int64_t now) {
     sqlite3_close(db);
     return result;
 }
+
+std::string scitokens::Validator::load_jwks(const std::string &issuer) {
+    auto now = std::time(NULL);
+    picojson::value jwks;
+    int64_t next_update;
+    
+    try {
+        // Try to get from cache
+        if (get_public_keys_from_db(issuer, now, jwks, next_update)) {
+            // Check if refresh is needed (expired based on next_update)
+            if (now <= next_update) {
+                // Still valid, return cached version
+                return jwks.serialize();
+            }
+            // Past next_update, need to refresh
+        }
+    } catch (const NegativeCacheHitException &) {
+        // Negative cache hit - return empty keys
+        return std::string("{\"keys\": []}");
+    }
+    
+    // Either not in cache or past next_update - refresh
+    if (!refresh_jwks(issuer)) {
+        throw CurlException("Failed to load JWKS for issuer: " + issuer);
+    }
+    
+    // Get the newly refreshed JWKS
+    return get_jwks(issuer);
+}
+
+std::string scitokens::Validator::get_jwks_metadata(const std::string &issuer) {
+    auto now = std::time(NULL);
+    int64_t next_update = -1;
+    int64_t expires = -1;
+    
+    // Get the metadata from database without expiry check
+    auto cache_fname = get_cache_file();
+    if (cache_fname.size() == 0) {
+        throw std::runtime_error("Unable to access cache file");
+    }
+    
+    sqlite3 *db;
+    int rc = sqlite3_open(cache_fname.c_str(), &db);
+    if (rc) {
+        sqlite3_close(db);
+        throw std::runtime_error("Failed to open cache database");
+    }
+    sqlite3_busy_timeout(db, SQLITE_BUSY_TIMEOUT_MS);
+    
+    sqlite3_stmt *stmt;
+    rc = sqlite3_prepare_v2(db, "SELECT keys from keycache where issuer = ?",
+                            -1, &stmt, NULL);
+    if (rc != SQLITE_OK) {
+        sqlite3_close(db);
+        throw std::runtime_error("Failed to prepare database query");
+    }
+    
+    if (sqlite3_bind_text(stmt, 1, issuer.c_str(), issuer.size(),
+                          SQLITE_STATIC) != SQLITE_OK) {
+        sqlite3_finalize(stmt);
+        sqlite3_close(db);
+        throw std::runtime_error("Failed to bind issuer to query");
+    }
+    
+    rc = sqlite3_step(stmt);
+    if (rc == SQLITE_ROW) {
+        const unsigned char *data = sqlite3_column_text(stmt, 0);
+        std::string metadata(reinterpret_cast<const char *>(data));
+        sqlite3_finalize(stmt);
+        sqlite3_close(db);
+        
+        picojson::value json_obj;
+        auto err = picojson::parse(json_obj, metadata);
+        if (!err.empty() || !json_obj.is<picojson::object>()) {
+            throw JsonException("Invalid JSON in cache entry");
+        }
+        
+        auto top_obj = json_obj.get<picojson::object>();
+        
+        // Extract expires
+        auto iter = top_obj.find("expires");
+        if (iter != top_obj.end() && iter->second.is<int64_t>()) {
+            expires = iter->second.get<int64_t>();
+        }
+        
+        // Extract next_update
+        iter = top_obj.find("next_update");
+        if (iter != top_obj.end() && iter->second.is<int64_t>()) {
+            next_update = iter->second.get<int64_t>();
+        } else if (expires != -1) {
+            // Default next_update to 4 hours before expiry
+            next_update = expires - 4 * 3600;
+        }
+        
+        // Build metadata JSON
+        picojson::object metadata_obj;
+        metadata_obj["expires"] = picojson::value(expires);
+        metadata_obj["next_update"] = picojson::value(next_update);
+        metadata_obj["extra"] = picojson::value(picojson::object());
+        
+        return picojson::value(metadata_obj).serialize();
+    } else {
+        sqlite3_finalize(stmt);
+        sqlite3_close(db);
+        throw std::runtime_error("Issuer not found in cache");
+    }
+}
+
+bool scitokens::Validator::delete_jwks(const std::string &issuer) {
+    auto cache_fname = get_cache_file();
+    if (cache_fname.size() == 0) {
+        return false;
+    }
+    
+    sqlite3 *db;
+    int rc = sqlite3_open(cache_fname.c_str(), &db);
+    if (rc) {
+        sqlite3_close(db);
+        return false;
+    }
+    sqlite3_busy_timeout(db, SQLITE_BUSY_TIMEOUT_MS);
+    
+    // Use the existing remove_issuer_entry function
+    if (remove_issuer_entry(db, issuer, true) != 0) {
+        return false;
+    }
+    
+    sqlite3_close(db);
+    return true;
+}
diff --git a/src/scitokens_internal.h b/src/scitokens_internal.h
@@ -1309,6 +1309,25 @@ class Validator {
     static std::vector<std::pair<std::string, int64_t>>
     get_all_issuers_from_db(int64_t now);
 
+    /**
+     * Load JWKS for a given issuer, refreshing only if needed.
+     * Returns the JWKS string. If refresh is needed and fails, throws exception.
+     */
+    static std::string load_jwks(const std::string &issuer);
+
+    /**
+     * Get metadata for a cached JWKS entry.
+     * Returns a JSON string with expires, next_update, and extra fields.
+     * Throws exception if issuer not found in cache.
+     */
+    static std::string get_jwks_metadata(const std::string &issuer);
+
+    /**
+     * Delete a JWKS entry from the keycache.
+     * Returns true on success, false on failure.
+     */
+    static bool delete_jwks(const std::string &issuer);
+
   private:
     static std::unique_ptr<AsyncStatus>
     get_public_key_pem(const std::string &issuer, const std::string &kid,
diff --git a/test/main.cpp b/test/main.cpp
@@ -955,6 +955,106 @@ TEST_F(KeycacheTest, NegativeCacheTest) {
         << "Should have 2 negative cache hits. JSON: " << json_str;
 }
 
+TEST_F(KeycacheTest, LoadJwksTest) {
+    // Test load API - should return cached JWKS without triggering refresh
+    char *err_msg = nullptr;
+    char *jwks = nullptr;
+    
+    // Load JWKS - should return cached version from SetUp()
+    auto rv = keycache_load_jwks(demo_scitokens_url.c_str(), &jwks, &err_msg);
+    ASSERT_TRUE(rv == 0) << (err_msg ? err_msg : "unknown error");
+    ASSERT_TRUE(jwks != nullptr);
+    std::string jwks_str(jwks);
+    free(jwks);
+    if (err_msg) free(err_msg);
+    
+    EXPECT_EQ(demo_scitokens, jwks_str);
+}
+
+TEST_F(KeycacheTest, LoadJwksMissingTest) {
+    // Test load API with missing issuer - should attempt refresh
+    char *err_msg = nullptr;
+    char *jwks = nullptr;
+    
+    // Try to load a non-existent issuer - will fail to refresh
+    auto rv = keycache_load_jwks("https://demo.scitokens.org/nonexistent", &jwks, &err_msg);
+    ASSERT_FALSE(rv == 0); // Should fail since issuer doesn't exist
+    if (err_msg) free(err_msg);
+}
+
+TEST_F(KeycacheTest, GetMetadataTest) {
+    // Test metadata API - should return expires and next_update
+    char *err_msg = nullptr;
+    char *metadata = nullptr;
+    
+    // Get metadata for cached issuer
+    auto rv = keycache_get_jwks_metadata(demo_scitokens_url.c_str(), &metadata, &err_msg);
+    ASSERT_TRUE(rv == 0) << (err_msg ? err_msg : "unknown error");
+    ASSERT_TRUE(metadata != nullptr);
+    std::string metadata_str(metadata);
+    free(metadata);
+    if (err_msg) free(err_msg);
+    
+    // Verify JSON structure - should have expires, next_update, and extra fields
+    EXPECT_NE(metadata_str.find("\"expires\":"), std::string::npos);
+    EXPECT_NE(metadata_str.find("\"next_update\":"), std::string::npos);
+    EXPECT_NE(metadata_str.find("\"extra\":"), std::string::npos);
+}
+
+TEST_F(KeycacheTest, GetMetadataMissingTest) {
+    // Test metadata API with missing issuer
+    char *err_msg = nullptr;
+    char *metadata = nullptr;
+    
+    // Try to get metadata for non-existent issuer
+    auto rv = keycache_get_jwks_metadata("https://demo.scitokens.org/unknown", &metadata, &err_msg);
+    ASSERT_FALSE(rv == 0); // Should fail
+    if (err_msg) free(err_msg);
+}
+
+TEST_F(KeycacheTest, DeleteJwksTest) {
+    // Test delete API
+    char *err_msg = nullptr;
+    
+    // First verify the issuer is in cache
+    char *jwks = nullptr;
+    auto rv = keycache_get_cached_jwks(demo_scitokens_url.c_str(), &jwks, &err_msg);
+    ASSERT_TRUE(rv == 0) << (err_msg ? err_msg : "unknown error");
+    ASSERT_TRUE(jwks != nullptr);
+    free(jwks);
+    if (err_msg) {
+        free(err_msg);
+        err_msg = nullptr;
+    }
+    
+    // Delete the entry
+    rv = keycache_delete_jwks(demo_scitokens_url.c_str(), &err_msg);
+    ASSERT_TRUE(rv == 0) << (err_msg ? err_msg : "unknown error");
+    if (err_msg) {
+        free(err_msg);
+        err_msg = nullptr;
+    }
+    
+    // Verify it's gone - get_cached_jwks should return empty keys
+    rv = keycache_get_cached_jwks(demo_scitokens_url.c_str(), &jwks, &err_msg);
+    ASSERT_TRUE(rv == 0) << (err_msg ? err_msg : "unknown error");
+    ASSERT_TRUE(jwks != nullptr);
+    std::string jwks_str(jwks);
+    free(jwks);
+    if (err_msg) free(err_msg);
+    
+    EXPECT_EQ(jwks_str, "{\"keys\": []}");
+}
+
+TEST_F(KeycacheTest, DeleteJwksNonExistentTest) {
+    // Test delete API with non-existent issuer - should not fail
+    char *err_msg = nullptr;
+    
+    auto rv = keycache_delete_jwks("https://demo.scitokens.org/never-existed", &err_msg);
+    ASSERT_TRUE(rv == 0) << (err_msg ? err_msg : "unknown error"); // Should succeed (idempotent)
+    if (err_msg) free(err_msg);
+}
+
 class IssuerSecurityTest : public ::testing::Test {
   protected:
     void SetUp() override {
