Add keycache load, metadata, and delete APIs

[Copilot]

Adds three keycache management APIs addressing gaps in the current API surface:

API Additions

• keycache_load_jwks(): Retrieves JWKS from cache, triggering refresh only if past next_update time. Fills gap between keycache_get_cached_jwks() (never refreshes) and keycache_refresh_jwks() (always refreshes).

• keycache_get_jwks_metadata(): Returns cache entry metadata as JSON:

  {
    "expires": 1765830626,
    "next_update": 1765485626,
    "extra": {}
  }

  The extra field allows future extensibility without breaking the API.

• keycache_delete_jwks(): Removes cache entry. Idempotent - succeeds even if entry doesn't exist.

Implementation Notes

• Internal implementations in scitokens_cache.cpp follow existing patterns
• Database connection lifecycle properly managed (avoids double-close via remove_issuer_entry)
• Magic number 4 * 3600 replaced with named constant DEFAULT_NEXT_UPDATE_OFFSET_S
• All three APIs include comprehensive unit tests covering normal operation, missing issuers, and edge cases

Example Usage

char *jwks = NULL, *metadata = NULL, *err_msg = NULL;

// Load JWKS, refreshing only if needed
keycache_load_jwks("https://issuer.example.com", &jwks, &err_msg);

// Get cache metadata
keycache_get_jwks_metadata("https://issuer.example.com", &metadata, &err_msg);

// Delete cache entry
keycache_delete_jwks("https://issuer.example.com", &err_msg);

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• demo.scitokens.org
  • Triggering command: ./test/scitokens-gtest ./test/scitokens-gtest --gtest_filter=KeycacheTest.LoadJwksTest:KeycacheTest.GetMetadataTest:KeycacheTest.DeleteJwksTest:KeycacheTest.DeleteJwksNonExistentTest:KeycacheTest.GetMetadataMissingTest:KeycacheTest.LoadJwksMissingTest (dns block)
  • Triggering command: ./test/scitokens-gtest ./test/scitokens-gtest --gtest_filter=KeycacheTest.* CMakeFiles/scitokens-gtest.dir/main.cpp.o /tmp/ccAOLmHV.s conf�� lude --local /usr/bin/git credential.helpeas (dns block)
  • Triggering command: ./test/scitokens-gtest ./test/scitokens-gtest ev/null || true;-I t.cpp.o me/REDACTED/work/s-I conf�� E cmake_depends "Unix Makefiles" /home/REDACTED/work/scitokens-cpp/scitokens-cpp /home/REDACTED/work/scitokens-cpp/scitokens-cpp /home/REDACTED/work/scitokens-cpp/scitokens-cpp/buil --local /home/REDACTED/.do-o user.name (dns block)
• esm.ubuntu.com
  • Triggering command: /usr/lib/apt/methods/https /usr/lib/apt/methods/https -dumpbase CMakeCXXCompilerId.cpp -dumpbase-ext .cpp -mtune=generic -march=x86-64 -fasynchronous-unwind-tables -fstack-protector-strong -Wformat -Wformat-security -fstack-clash-protection (dns block)
• invalid-issuer-negative-cache-1765484953.example.com
  • Triggering command: ./test/scitokens-gtest ./test/scitokens-gtest --gtest_filter=KeycacheTest.* CMakeFiles/scitokens-gtest.dir/main.cpp.o /tmp/ccAOLmHV.s conf�� lude --local /usr/bin/git credential.helpeas (dns block)
• invalid-issuer-negative-cache-1765484964.example.com
  • Triggering command: ./test/scitokens-gtest ./test/scitokens-gtest ev/null || true;-I t.cpp.o me/REDACTED/work/s-I conf�� E cmake_depends "Unix Makefiles" /home/REDACTED/work/scitokens-cpp/scitokens-cpp /home/REDACTED/work/scitokens-cpp/scitokens-cpp /home/REDACTED/work/scitokens-cpp/scitokens-cpp/buil --local /home/REDACTED/.do-o user.name (dns block)
• invalid-issuer-negative-cache-1765485277.example.com
  • Triggering command: ./test/scitokens-gtest ./test/scitokens-gtest --gtest_filter=KeycacheTest.* (dns block)
• invalid-issuer-negative-cache-1765485335.example.com
  • Triggering command: ./test/scitokens-gtest ./test/scitokens-gtest c/verify.cpp (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add more keycache APIs</issue_title>
<issue_description>1. The keycache API has the ability to "refresh" the issuer (forcing an update, regardless of whether it's needed); there's also "get" that retrieves the current state in the database. However, there's no easy way to query an issuer and only trigger a refresh if needed ("load"?).
2. There's no API for metadata (you can get the JWKS contents but not the expiration time or next_update).
3. There's no API for deleting a keycache entry.

Add these APIs; for the metadata API, allow arbitrary extra information to be included as a JSON string output (currently empty is OK).

Make sure to include unit (or, as necessary, integration) tests showing the functionality works as desired.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Add more keycache APIs #193

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[bbockelm]

LGTM.