feat: Add Vault integration library to authlib

[Alan-Cha]

Summary

Implements Phase 1 of the Vault pattern: a reusable Go library (authlib/vault) for Hashicorp Vault integration with SPIFFE JWT-SVID authentication support.

This enables Kagenti workloads to retrieve static credentials (API keys, database passwords, service tokens) from Vault using their SPIFFE identity for authentication.

Features

Authentication Methods (SPIFFE Priority)

• ✅ JWT/OIDC auth — Uses SPIFFE JWT-SVID (priority 1)
• ✅ Kubernetes service account auth — Fallback option
• ✅ Token auth — Dev/testing

Secret Operations

• ✅ KV v1/v2 auto-detection — Works with both Vault secret engine versions
• ✅ Single & batch secret reading — Efficient multi-secret fetching
• ✅ Secret listing — Discovery of available secrets

Caching & Renewal

• ✅ Lease-aware caching — Cache TTL respects Vault lease durations
• ✅ Background token renewal — Automatic renewal at 2/3 of lease duration
• ✅ Thread-safe operations — Concurrent access with proper locking

Quality

• ✅ Typed errors — Better error handling and debugging
• ✅ Unit tests — All tests passing
• ✅ Comprehensive documentation — README with examples, architecture docs

Code Reuse & Attribution

This implementation follows patterns from:

• Klaviger (github.com/grs/klaviger) — KV auto-detection, K8s SA auth, lease-aware caching (~60% of core Vault logic)
• IBM Trusted Service Identity examples — JWT/OIDC auth pattern for SPIFFE workloads
• Hashicorp Vault Go SDK documentation

Key improvements over Klaviger:

• JWT/OIDC auth method added (critical for SPIFFE workloads)
• Background token renewal implemented (was TODO in Klaviger)
• Batch secret reading support
• Typed error system

Files Added

Core library:

• authbridge/authlib/vault/auth.go (319 lines) — Authentication with renewal
• authbridge/authlib/vault/cache.go (145 lines) — Lease-aware caching
• authbridge/authlib/vault/client.go (202 lines) — Main client wrapper
• authbridge/authlib/vault/config.go (133 lines) — Configuration with validation
• authbridge/authlib/vault/errors.go (66 lines) — Typed errors
• authbridge/authlib/vault/secret.go (142 lines) — KV v1/v2 secret reading
• authbridge/authlib/vault/config_test.go (130 lines) — Unit tests
• authbridge/authlib/vault/README.md (379 lines) — Complete documentation

Documentation:

• VAULT_PATTERN_OVERVIEW.md (282 lines) — Architecture and use cases
• VAULT_IMPLEMENTATION_PLAN.md (690 lines) — 4-phase implementation plan
• KLAVIGER_ANALYSIS.md (423 lines) — Code reuse analysis
• VAULT_PHASE1_COMPLETE.md (293 lines) — Phase 1 summary

Dependencies:

• Updated authbridge/authlib/go.mod — Added hashicorp/vault/api v1.23.0
• Updated authbridge/authlib/README.md — Added vault package to table

Total: ~3,270 lines added

Usage Example

```go
// Create client with JWT auth (SPIFFE)
cfg := &vault.Config{
Address: "https://vault.example.com",
AuthMethod: "jwt",
Role: "github-agent-role",
JWTPath: "/opt/jwt_svid.token",
}
client, _ := vault.NewClient(cfg)
defer client.Close()

// Authenticate (token renewal happens automatically in background)
ctx := context.Background()
client.Authenticate(ctx)

// Read secret (with automatic caching)
token, leaseDuration, _ := client.ReadSecret(ctx,
"secret/data/github/token",
"token")
```

Testing

```bash
$ cd authbridge/authlib
$ go test ./vault/... -v
=== RUN TestConfigValidate
--- PASS: TestConfigValidate (0.00s)
=== RUN TestConfigDefaults
--- PASS: TestConfigDefaults (0.00s)
PASS
ok github.com/kagenti/kagenti-extensions/authbridge/authlib/vault 0.493s

$ go build ./vault/...

Clean build ✅

```

Architecture

This library is a pure library (no protocol dependencies) that will be used by:

1. Phase 2: vault-fetcher CLI tool (init container)
2. Phase 3 (optional): AuthBridge unified binary (dynamic Vault injection mode)

The library does NOT modify the existing AuthBridge unified binary. It's a new reusable component.

Next Steps (Not in this PR)

• Phase 2: Create vault-fetcher CLI tool and Docker image
• Phase 3: Webhook integration for automatic injection
• Phase 4: Demo and documentation

Review Notes

Key areas to review:

1. Security: Auth methods, token handling, caching strategy
2. API design: Does the Client interface make sense?
3. Attribution: Proper credit to Klaviger and IBM TSI?
4. Documentation: Clear enough for developers?
5. Testing: Sufficient coverage for Phase 1?

Questions for reviewers:

• Should we enforce a specific cache TTL default, or leave it fully configurable?
• Any concerns about the background token renewal approach?
• Should we add more validation in Config.Validate()?

Assisted-By: Claude (Anthropic AI) noreply@anthropic.com

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed in 14 days if no further activity occurs. If this PR is still relevant, please comment or remove the stale label.

[mrsabath]

We are putting Vault activity on hold until we figure out whether this work should be done by CPEX or directly in Cortex.