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