kcc-cache: default TTL for no-expiry credentials + debug mode (#11)

Some credential plugins (e.g. the passman krew plugin) emit an
ExecCredential without a status.expirationTimestamp, which decodes to the
zero time. Such credentials look permanently expired, so they were
re-fetched on every call and never effectively cached despite leaving an
entry in the OS secret store.

When a refreshed credential's expiry is more than
KUBE_CREDENTIAL_CACHE_NO_EXPIRY_THRESHOLD (default 24h) in the past, treat
it as "no expiry provided" and cache it for KUBE_CREDENTIAL_CACHE_DEFAULT_TTL
(default 1h). Genuinely recently-expired credentials still refresh.

Add KUBE_CREDENTIAL_CACHE_DEBUG to log the cache key, backend, hit/miss,
expiry and refresh decisions to stderr (never credential material).


Claude-Session: https://claude.ai/code/session_01XP6Vo1jhL3S96g8hQ76umo

Co-authored-by: Claude <noreply@anthropic.com>

Author: IvMisticos

README.md

@@ -162,6 +162,21 @@ Clear the cache: delete the `kube-credential-cache` entries from your OS secret
 ###### `...Corruption detected, recreate cache file`
 A broken cache file was detected. The cause is unknown; the cache is automatically recreated.
 
+###### kubectl keeps re-running the credential plugin / prompting on every call
+The credential is being written to your secret store but never served from cache.
+The usual cause is a plugin that returns no `status.expirationTimestamp` (it shows
+up as `"expirationTimestamp":"0001-01-01T00:00:00Z"`), so kcc-cache considers it
+already expired every time. Set `KUBE_CREDENTIAL_CACHE_DEBUG=1` to see the cache
+key, hit/miss and expiry decisions on stderr. The default-TTL behaviour (above)
+handles this automatically; tune it with `KUBE_CREDENTIAL_CACHE_DEFAULT_TTL` and
+`KUBE_CREDENTIAL_CACHE_NO_EXPIRY_THRESHOLD`.
+
+> :information_source: In the OS secret store each cached credential is a single
+> entry whose name is `kube-credential-cache:<cache-key>` (e.g.
+> `kube-credential-cache:user="..." server="..."`). The `kube-credential-cache:`
+> prefix is just the service name; the rest is the cache key — it is one entry,
+> not two separate keys.
+
 ## Configuration
 
 ### kcc-cache
@@ -171,7 +186,24 @@ A broken cache file was detected. The cause is unknown; the cache is automatical
 | KUBE_CREDENTIAL_CACHE_BACKEND           | _auto_ (`keyring` if the OS secret store is reachable, otherwise `file`)                                                                                                                                                                        | storage backend: `keyring` or `file`               |
 | KUBE_CREDENTIAL_CACHE_FILE              | macOS:</br>`~/Library/Caches/kube-credential-cache/cache.json`</br>Linux:</br>`$XDG_CACHE_HOME/kube-credential-cache/cache.json`</br>`~/.cache/kube-credential-cache/cache.json`</br>Windows:</br>`%AppData%\kube-credential-cache\cache.json` | path of Cache file (`file` backend only)           |
 | KUBE_CREDENTIAL_CACHE_REFRESH_MARGIN    | `30s`                                                                                                                                                                                                                                          | margin of credential refresh                       |
+| KUBE_CREDENTIAL_CACHE_DEFAULT_TTL       | `1h`                                                                                                                                                                                                                                          | TTL applied to credentials that report no usable expiry (see below) |
+| KUBE_CREDENTIAL_CACHE_NO_EXPIRY_THRESHOLD | `24h`                                                                                                                                                                                                                                        | how far in the past a credential's expiry must be to count as "no expiry" |
 | KUBE_CREDENTIAL_CACHE_CACHEKEY_ENV_LIST | `KUBE_CREDENTIAL_CACHE_USER,AWS_PROFILE,AWS_REGION,AWS_VAULT`                                                                                                                                                                                  | comma separated env names for additional cache-key |
+| KUBE_CREDENTIAL_CACHE_DEBUG             | _unset_                                                                                                                                                                                                                                       | when set to a truthy value (`1`/`true`/`yes`/`on`), log cache key, hit/miss, expiry and refresh decisions to stderr |
+
+#### Credentials without an expiry (default TTL)
+
+Some credential plugins (for example the [passman](https://github.com/abenz1267/passman)
+krew plugin) emit an `ExecCredential` with no `status.expirationTimestamp`. That
+decodes to the zero time (`0001-01-01T00:00:00Z`), so the credential looks
+permanently expired and would be re-fetched on **every** call — defeating the
+cache while still leaving an entry in your secret store.
+
+To handle this, when a refreshed credential's expiry is more than
+`KUBE_CREDENTIAL_CACHE_NO_EXPIRY_THRESHOLD` (default `24h`) in the past, kcc-cache
+treats it as "no expiry provided" and caches it for
+`KUBE_CREDENTIAL_CACHE_DEFAULT_TTL` (default `1h`) instead. Genuinely
+recently-expired credentials (within the threshold) still refresh as before.
 
 #### Storage backends
 

cmd/kcc-cache/main.go

@@ -68,6 +68,8 @@ func main() {
 	// configuration
 	var (
 		refreshMargin   = time.Second * 30
+		defaultTTL      = time.Hour
+		noExpiryCutoff  = time.Hour * 24
 		cacheKeyEnvlist = []string{"KUBE_CREDENTIAL_CACHE_USER", "AWS_PROFILE", "AWS_REGION", "AWS_VAULT"}
 	)
 	if e := os.Getenv("KUBE_CREDENTIAL_CACHE_REFRESH_MARGIN"); e != "" {
@@ -77,9 +79,24 @@ func main() {
 		}
 		refreshMargin = d
 	}
+	if e := os.Getenv("KUBE_CREDENTIAL_CACHE_DEFAULT_TTL"); e != "" {
+		d, err := time.ParseDuration(e)
+		if err != nil {
+			fatal("invalid environment variable 'KUBE_CREDENTIAL_CACHE_DEFAULT_TTL': %s", err.Error())
+		}
+		defaultTTL = d
+	}
+	if e := os.Getenv("KUBE_CREDENTIAL_CACHE_NO_EXPIRY_THRESHOLD"); e != "" {
+		d, err := time.ParseDuration(e)
+		if err != nil {
+			fatal("invalid environment variable 'KUBE_CREDENTIAL_CACHE_NO_EXPIRY_THRESHOLD': %s", err.Error())
+		}
+		noExpiryCutoff = d
+	}
 	if e := os.Getenv("KUBE_CREDENTIAL_CACHE_CACHEKEY_ENV_LIST"); e != "" {
 		cacheKeyEnvlist = strings.Split(e, ",")
 	}
+	debugEnabled = isTruthy(os.Getenv("KUBE_CREDENTIAL_CACHE_DEBUG"))
 
 	// cache key
 	//
@@ -126,16 +143,25 @@ func main() {
 		}
 	}
 
+	debugf("cache key: %s", cacheKey)
+
 	// select storage backend
 	backend := newBackend(os.Getenv("KUBE_CREDENTIAL_CACHE_BACKEND"))
+	debugf("backend: %T (KUBE_CREDENTIAL_CACHE_BACKEND=%q)", backend, os.Getenv("KUBE_CREDENTIAL_CACHE_BACKEND"))
 
 	// check cache
 	cache, ok, err := backend.Get(cacheKey)
 	if err != nil {
 		fatal("cache read failed: %s", err)
 	}
+	if ok {
+		debugf("cache hit: expires %s (in %s)", cache.Status.ExpirationTimestamp.Format(time.RFC3339), time.Until(cache.Status.ExpirationTimestamp).Round(time.Second))
+	} else {
+		debugf("cache miss")
+	}
 	if !ok || time.Until(cache.Status.ExpirationTimestamp) < refreshMargin {
 		// refresh (os.Args[1] is guaranteed present; checked at startup)
+		debugf("refreshing: running %q", strings.Join(os.Args[1:], " "))
 		cmd := exec.Command(os.Args[1], os.Args[2:]...)
 		cmd.Stderr = os.Stderr
 		bytes, err := cmd.Output()
@@ -156,9 +182,28 @@ func main() {
 			fatal("json.Unmarshal() failed(read command output): %s\nactual stdout: %s", err, string(bytes))
 		}
 
+		// default TTL for credentials without a usable expiry
+		//
+		// Some credential plugins (e.g. the passman krew plugin) emit an
+		// ExecCredential without a status.expirationTimestamp, which decodes to
+		// the zero time (0001-01-01T00:00:00Z). Such a credential is always
+		// "expired", so it would be re-fetched on every single call and never
+		// effectively cached. When the reported expiry is implausibly far in the
+		// past (more than noExpiryCutoff ago) we treat it as "no expiry provided"
+		// and substitute now+defaultTTL, while leaving genuinely-recently-expired
+		// credentials to refresh as before.
+		if adjusted, ok := withDefaultExpiry(cache, noExpiryCutoff, defaultTTL, time.Now()); ok {
+			debugf("credential expiration %s is more than %s in the past; treating as no-expiry and applying default TTL %s (expires %s)",
+				cache.Status.ExpirationTimestamp.Format(time.RFC3339), noExpiryCutoff, defaultTTL, adjusted.Status.ExpirationTimestamp.Format(time.RFC3339))
+			cache = adjusted
+		}
+
 		if err := backend.Set(cacheKey, cache); err != nil {
 			fatal("cache write failed: %s", err)
 		}
+		debugf("stored credential (expires %s)", cache.Status.ExpirationTimestamp.Format(time.RFC3339))
+	} else {
+		debugf("serving from cache")
 	}
 
 	// print
@@ -344,3 +389,39 @@ func log(format string, v ...any) {
 	fmt.Fprintf(os.Stderr, "%s: ", path.Base(os.Args[0]))
 	fmt.Fprintf(os.Stderr, format+"\n", v...)
 }
+
+// debugEnabled gates verbose diagnostics, controlled by KUBE_CREDENTIAL_CACHE_DEBUG.
+var debugEnabled bool
+
+// debugf logs a diagnostic line to stderr when debug output is enabled. It never
+// logs credential material (tokens / key data), only cache keys and metadata.
+func debugf(format string, v ...any) {
+	if !debugEnabled {
+		return
+	}
+	log("[debug] "+format, v...)
+}
+
+// withDefaultExpiry substitutes a default expiry for credentials that report no
+// usable one. When the credential's expiration is more than cutoff before now
+// (e.g. the zero time emitted by plugins like passman), it returns a copy with
+// the expiration set to now+ttl and ok=true. Otherwise it returns the credential
+// unchanged with ok=false, so genuinely-recently-expired credentials still refresh.
+func withDefaultExpiry(cred ClientAuthentication, cutoff, ttl time.Duration, now time.Time) (ClientAuthentication, bool) {
+	if now.Sub(cred.Status.ExpirationTimestamp) > cutoff {
+		cred.Status.ExpirationTimestamp = now.Add(ttl)
+		return cred, true
+	}
+	return cred, false
+}
+
+// isTruthy reports whether an environment variable value should be treated as
+// "on". Anything set and not explicitly falsey enables the feature.
+func isTruthy(v string) bool {
+	switch strings.ToLower(strings.TrimSpace(v)) {
+	case "", "0", "false", "no", "off":
+		return false
+	default:
+		return true
+	}
+}

cmd/kcc-cache/main_test.go

@@ -48,6 +48,52 @@ func testBackendRoundTrip(t *testing.T, b Backend) {
 	}
 }
 
+func TestWithDefaultExpiry(t *testing.T) {
+	now := time.Date(2026, 6, 19, 12, 0, 0, 0, time.UTC)
+	cutoff := 24 * time.Hour
+	ttl := time.Hour
+
+	tests := []struct {
+		name    string
+		exp     time.Time
+		wantOK  bool
+		wantExp time.Time
+	}{
+		{"zero time (no expiry, e.g. passman)", time.Time{}, true, now.Add(ttl)},
+		{"far past beyond cutoff", now.Add(-48 * time.Hour), true, now.Add(ttl)},
+		{"recently expired within cutoff", now.Add(-time.Hour), false, now.Add(-time.Hour)},
+		{"valid future expiry", now.Add(2 * time.Hour), false, now.Add(2 * time.Hour)},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cred := newCred("tok")
+			cred.Status.ExpirationTimestamp = tt.exp
+
+			got, ok := withDefaultExpiry(cred, cutoff, ttl, now)
+			if ok != tt.wantOK {
+				t.Fatalf("ok = %v, want %v", ok, tt.wantOK)
+			}
+			if !got.Status.ExpirationTimestamp.Equal(tt.wantExp) {
+				t.Fatalf("expiration = %s, want %s", got.Status.ExpirationTimestamp, tt.wantExp)
+			}
+		})
+	}
+}
+
+func TestIsTruthy(t *testing.T) {
+	for _, v := range []string{"", "0", "false", "no", "off", "  off  ", "FALSE"} {
+		if isTruthy(v) {
+			t.Errorf("isTruthy(%q) = true, want false", v)
+		}
+	}
+	for _, v := range []string{"1", "true", "yes", "on", "debug", "TRUE"} {
+		if !isTruthy(v) {
+			t.Errorf("isTruthy(%q) = false, want true", v)
+		}
+	}
+}
+
 func TestKeyringBackend(t *testing.T) {
 	keyring.MockInit()
 	testBackendRoundTrip(t, keyringBackend{})