Add offline support with SCITOKENS_KEYCACHE_FILE and scitokens-keycache tool

Copilot · djw8605 · Copilot · commit 6d369a9b7ae9 · 2025-08-13T20:53:15.000Z
Co-authored-by: djw8605 &lt;79268+djw8605@users.noreply.github.com&gt;
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -75,6 +75,9 @@ target_link_libraries(scitokens-list-access SciTokens)
 add_executable(scitokens-create src/create.cpp)
 target_link_libraries(scitokens-create SciTokens)
 
+add_executable(scitokens-keycache src/scitokens-keycache.cpp)
+target_link_libraries(scitokens-keycache SciTokens)
+
 get_directory_property(TARGETS BUILDSYSTEM_TARGETS)
 install(
   TARGETS ${TARGETS} 
diff --git a/src/scitokens-keycache.cpp b/src/scitokens-keycache.cpp
@@ -0,0 +1,145 @@
+#include <cstdlib>
+#include <cstring>
+#include <ctime>
+#include <iostream>
+#include <fstream>
+#include <string>
+#include <unistd.h>
+
+#include "scitokens.h"
+
+void print_usage(const char *progname) {
+    std::cout << "Usage: " << progname << " --cache-file <cache_file> --jwks <jwks_file> --issuer <issuer> --valid-for <seconds>\n";
+    std::cout << "\n";
+    std::cout << "Options:\n";
+    std::cout << "  --cache-file <file>   Path to the keycache SQLite database file\n";
+    std::cout << "  --jwks <file>         Path to the JWKS file to store\n";
+    std::cout << "  --issuer <issuer>     Issuer URL for the JWKS\n";
+    std::cout << "  --valid-for <seconds> How long the key should be valid (in seconds)\n";
+    std::cout << "  --help               Show this help message\n";
+    std::cout << "\n";
+    std::cout << "Example:\n";
+    std::cout << "  " << progname << " --cache-file /tmp/offline.db --jwks keys.json --issuer https://example.com --valid-for 86400\n";
+}
+
+std::string read_file(const std::string &filename) {
+    std::ifstream file(filename);
+    if (!file.is_open()) {
+        throw std::runtime_error("Cannot open file: " + filename);
+    }
+    
+    std::string content((std::istreambuf_iterator<char>(file)),
+                        std::istreambuf_iterator<char>());
+    return content;
+}
+
+int main(int argc, char *argv[]) {
+    std::string cache_file;
+    std::string jwks_file;
+    std::string issuer;
+    long valid_for = 0;
+    
+    // Parse command line arguments
+    for (int i = 1; i < argc; i++) {
+        if (strcmp(argv[i], "--help") == 0) {
+            print_usage(argv[0]);
+            return 0;
+        } else if (strcmp(argv[i], "--cache-file") == 0) {
+            if (i + 1 >= argc) {
+                std::cerr << "Error: --cache-file requires an argument\n";
+                return 1;
+            }
+            cache_file = argv[++i];
+        } else if (strcmp(argv[i], "--jwks") == 0) {
+            if (i + 1 >= argc) {
+                std::cerr << "Error: --jwks requires an argument\n";
+                return 1;
+            }
+            jwks_file = argv[++i];
+        } else if (strcmp(argv[i], "--issuer") == 0) {
+            if (i + 1 >= argc) {
+                std::cerr << "Error: --issuer requires an argument\n";
+                return 1;
+            }
+            issuer = argv[++i];
+        } else if (strcmp(argv[i], "--valid-for") == 0) {
+            if (i + 1 >= argc) {
+                std::cerr << "Error: --valid-for requires an argument\n";
+                return 1;
+            }
+            char *endptr;
+            valid_for = strtol(argv[++i], &endptr, 10);
+            if (*endptr != '\0' || valid_for <= 0) {
+                std::cerr << "Error: --valid-for must be a positive integer\n";
+                return 1;
+            }
+        } else {
+            std::cerr << "Error: Unknown option " << argv[i] << "\n";
+            print_usage(argv[0]);
+            return 1;
+        }
+    }
+    
+    // Validate required arguments
+    if (cache_file.empty()) {
+        std::cerr << "Error: --cache-file is required\n";
+        print_usage(argv[0]);
+        return 1;
+    }
+    if (jwks_file.empty()) {
+        std::cerr << "Error: --jwks is required\n";
+        print_usage(argv[0]);
+        return 1;
+    }
+    if (issuer.empty()) {
+        std::cerr << "Error: --issuer is required\n";
+        print_usage(argv[0]);
+        return 1;
+    }
+    if (valid_for == 0) {
+        std::cerr << "Error: --valid-for is required\n";
+        print_usage(argv[0]);
+        return 1;
+    }
+    
+    try {
+        // Set the cache file environment variable
+        if (setenv("SCITOKENS_KEYCACHE_FILE", cache_file.c_str(), 1) != 0) {
+            std::cerr << "Error: Failed to set SCITOKENS_KEYCACHE_FILE environment variable\n";
+            return 1;
+        }
+        
+        // Read the JWKS file
+        std::string jwks_content = read_file(jwks_file);
+        
+        // Calculate expiration time
+        time_t now = time(nullptr);
+        int64_t expires_at = static_cast<int64_t>(now) + valid_for;
+        
+        // Store the JWKS with expiration
+        char *err_msg = nullptr;
+        int result = keycache_set_jwks_with_expiry(issuer.c_str(), jwks_content.c_str(), expires_at, &err_msg);
+        
+        if (result != 0) {
+            std::cerr << "Error: Failed to store JWKS: " << (err_msg ? err_msg : "Unknown error") << "\n";
+            if (err_msg) {
+                free(err_msg);
+            }
+            return 1;
+        }
+        
+        std::cout << "Successfully stored JWKS for issuer: " << issuer << "\n";
+        std::cout << "Cache file: " << cache_file << "\n";
+        std::cout << "Expires at: " << ctime(&now) << " + " << valid_for << " seconds\n";
+        
+        if (err_msg) {
+            free(err_msg);
+        }
+        
+    } catch (const std::exception &e) {
+        std::cerr << "Error: " << e.what() << "\n";
+        return 1;
+    }
+    
+    return 0;
+}
diff --git a/src/scitokens.cpp b/src/scitokens.cpp
@@ -989,6 +989,36 @@ int keycache_set_jwks(const char *issuer, const char *jwks, char **err_msg) {
     return 0;
 }
 
+int keycache_set_jwks_with_expiry(const char *issuer, const char *jwks, 
+                                  int64_t expires_at, 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 pointer may not be null.");
+        }
+        return -1;
+    }
+    try {
+        if (!scitokens::Validator::store_jwks_with_expiry(issuer, jwks, expires_at)) {
+            if (err_msg) {
+                *err_msg = strdup("Failed to set the JWKS cache 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
@@ -290,6 +290,15 @@ int keycache_get_cached_jwks(const char *issuer, char **jwks, char **err_msg);
  */
 int keycache_set_jwks(const char *issuer, const char *jwks, char **err_msg);
 
+/**
+ * Replace any existing key cache entry with one provided by the user.
+ * Allows explicit setting of expiration time for offline usage.
+ * - `jwks` is value that will be set in the cache.
+ * - `expires_at` is the expiration time as Unix timestamp (seconds since epoch).
+ */
+int keycache_set_jwks_with_expiry(const char *issuer, const char *jwks, 
+                                  int64_t expires_at, char **err_msg);
+
 /**
  * APIs for managing scitokens configuration parameters.
  */
diff --git a/src/scitokens_cache.cpp b/src/scitokens_cache.cpp
@@ -42,13 +42,22 @@ void initialize_cachedb(const std::string &keycache_file) {
 
 /**
  * Get the Cache file location
- *  1. User-defined through config api
- *  2. $XDG_CACHE_HOME
- *  3. .cache subdirectory of home directory as returned by the password
+ *  1. SCITOKENS_KEYCACHE_FILE environment variable (for offline use)
+ *  2. User-defined through config api
+ *  3. $XDG_CACHE_HOME
+ *  4. .cache subdirectory of home directory as returned by the password
  * database
  */
 std::string get_cache_file() {
 
+    // Check for direct cache file location first (offline support)
+    const char *direct_cache_file = getenv("SCITOKENS_KEYCACHE_FILE");
+    if (direct_cache_file && strlen(direct_cache_file) > 0) {
+        std::string keycache_file(direct_cache_file);
+        initialize_cachedb(keycache_file);
+        return keycache_file;
+    }
+
     const char *xdg_cache_home = getenv("XDG_CACHE_HOME");
 
     auto bufsize = sysconf(_SC_GETPW_R_SIZE_MAX);
diff --git a/src/scitokens_internal.cpp b/src/scitokens_internal.cpp
@@ -797,6 +797,20 @@ bool Validator::store_jwks(const std::string &issuer,
     return store_public_keys(issuer, jwks, next_update, expires);
 }
 
+bool Validator::store_jwks_with_expiry(const std::string &issuer,
+                                       const std::string &jwks_str,
+                                       int64_t expires_at) {
+    picojson::value jwks;
+    std::string err = picojson::parse(jwks, jwks_str);
+    auto now = std::time(NULL);
+    int next_update_delta = configurer::Configuration::get_next_update_delta();
+    int64_t next_update = now + next_update_delta;
+    if (!err.empty()) {
+        throw JsonException(err);
+    }
+    return store_public_keys(issuer, jwks, next_update, expires_at);
+}
+
 std::unique_ptr<AsyncStatus>
 Validator::get_public_key_pem(const std::string &issuer, const std::string &kid,
                               std::string &public_pem, std::string &algorithm) {
diff --git a/src/scitokens_internal.h b/src/scitokens_internal.h
@@ -745,6 +745,13 @@ class Validator {
      */
     static bool store_jwks(const std::string &issuer, const std::string &jwks);
 
+    /**
+     * Store the contents of a JWKS for a given issuer with explicit expiry time.
+     */
+    static bool store_jwks_with_expiry(const std::string &issuer,
+                                       const std::string &jwks_str,
+                                       int64_t expires_at);
+
     /**
      * Trigger a refresh of the JWKS or a given issuer.
      */
