auth

Auth Package

Multi-provider authentication framework for scafctl with pluggable handlers, encrypted token caching, and a shared token-acquisition pipeline.

Features

• Pluggable Handlers: Register any number of auth providers (Entra ID, GCP, GitHub) via a thread-safe Registry
• Encrypted Token Cache: Disk-backed cache using pkg/secrets, keyed by (flow, fingerprint, scope)
• Generic Token Pipeline: Shared GetCachedOrAcquireToken[T] eliminates boilerplate across handlers
• Normalized Claims: Common Claims struct maps provider-specific identity data into a single shape
• Sentinel Errors: Typed errors (ErrNotAuthenticated, ErrTokenExpired, ErrInvalidScope, etc.) for programmatic error handling
• Optional Interfaces: Handlers can implement TokenLister, TokenPurger, or GroupsProvider for extended capabilities
• Context Integration: Store and retrieve the Registry via context.Context helpers

Architecture

pkg/auth/
├── handler.go        # Handler interface, Flow/Token/Status types
├── registry.go       # Thread-safe handler registry
├── context.go        # Context helpers (WithRegistry, RegistryFromContext)
├── cache.go          # TokenCache — encrypted disk cache via pkg/secrets
├── token_acquire.go  # GetCachedOrAcquireToken[T] — shared generic pipeline
├── claims.go         # Normalized identity claims
├── errors.go         # Sentinel errors and helpers
├── flow.go           # ParseFlow — user-facing flow string → Flow constant
├── capability.go     # Handler capability flags
├── fingerprint.go    # SHA-256 identity fingerprint for cache keys
├── groups.go         # Optional GroupsProvider interface
├── mock.go           # MockHandler for testing
├── entra/            # Microsoft Entra ID handler
├── gcp/              # Google Cloud Platform handler
├── github/           # GitHub handler
└── oauth/            # Shared OAuth 2.0 utilities (PKCE, callback server)

Core Interface

Every handler implements Handler:

type Handler interface {
    Name() string
    DisplayName() string
    Login(ctx context.Context, opts LoginOptions) (*Result, error)
    Logout(ctx context.Context) error
    Status(ctx context.Context) (*Status, error)
    GetToken(ctx context.Context, opts TokenOptions) (*Token, error)
    InjectAuth(ctx context.Context, req *http.Request, opts TokenOptions) error
    SupportedFlows() []Flow
    Capabilities() []Capability
}

Supported Flows

Quick Start

Register Handlers

reg := auth.NewRegistry()

entraHandler, _ := entra.New(entra.WithConfig(entraConfig))
reg.Register(entraHandler)

gcpHandler, _ := gcp.New(gcp.WithConfig(gcpConfig))
reg.Register(gcpHandler)

// Attach to context
ctx = auth.WithRegistry(ctx, reg)

Login

handler, _ := auth.GetHandler(ctx, "gcp")
result, err := handler.Login(ctx, auth.LoginOptions{
    Flow:   auth.FlowServicePrincipal,
    Scopes: []string{"https://www.googleapis.com/auth/cloud-platform"},
})

Acquire a Token

token, err := handler.GetToken(ctx, auth.TokenOptions{
    Flow:  auth.FlowServicePrincipal,
    Scope: "https://www.googleapis.com/auth/cloud-platform",
})

Inject Into HTTP Requests

req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
err := handler.InjectAuth(ctx, req, auth.TokenOptions{
    Scope: "https://www.googleapis.com/auth/cloud-platform",
})
// req now has Authorization: Bearer <token>

Token Cache

TokenCache provides encrypted, disk-backed token storage via pkg/secrets.

Cache keys follow the pattern <prefix>:<flow>:<fingerprint>:<scope> where the fingerprint is a truncated SHA-256 of the identity (e.g. client email or tenant+client ID).

cache := auth.NewTokenCache(secretStore, "gcp-token")

// Store
cache.Set(ctx, auth.FlowServicePrincipal, "fingerprint", "scope", token)

// Retrieve (returns nil if missing or expired)
cached, _ := cache.Get(ctx, auth.FlowServicePrincipal, "fingerprint", "scope")

// Housekeeping
cache.PurgeExpired(ctx)
cache.Clear(ctx)

Shared Token Pipeline

GetCachedOrAcquireToken[T] is the generic function all handlers use for the cache → acquire → store cycle:

token, err := auth.GetCachedOrAcquireToken(
    ctx,
    handler.tokenCache,
    opts,
    auth.FlowServicePrincipal,
    opts.Scope,                                    // cache key
    func() (*Creds, error) { return loadCreds() }, // credential loader
    func(c *Creds) bool { return c == nil },       // nil check
    func(c *Creds) string { return fingerprint },  // cache fingerprint
    func(ctx context.Context, c *Creds, scope string) (*auth.Token, error) {
        return acquireToken(ctx, c, scope)         // actual token acquisition
    },
    "MyFlow",                                      // log prefix
)

Sentinel Errors

| Error | When | |-----------------------------|--------------------------------------------|\n| ErrNotAuthenticated | No cached credentials available |\n| ErrAuthenticationFailed | Login or token acquisition failed |\n| ErrTokenExpired | Cached token past expiry |\n| ErrInvalidScope | Empty or missing scope |\n| ErrConsentRequired | User interaction needed |\n| ErrHandlerNotFound | Handler not in registry |\n| ErrFlowNotSupported | Handler doesn't support requested flow |\n| ErrUserCancelled | User aborted interactive flow |\n| ErrTimeout | Operation timed out |\n| ErrAlreadyAuthenticated | Already logged in |\n| ErrGrantInvalid | Refresh token or grant revoked |\n| ErrCapabilityNotSupported | Handler lacks required capability |

Provider-specific sentinel errors follow the same pattern:

• gcp.ErrNoServiceAccountConfigured
• gcp.ErrNoWorkloadIdentityConfigured
• gcp.ErrNoGcloudADCConfigured

Testing

Use MockHandler for unit testing code that depends on auth:

mock := auth.NewMockHandler("mock")
mock.SetToken(&auth.Token{AccessToken: "test-token", TokenType: "Bearer", ExpiresAt: time.Now().Add(time.Hour)})

Each sub-package also exposes mocks (e.g. gcp.NewMockHTTPClient()) for testing handler internals.

Capabilities

Handlers declare capabilities to let callers discover feature support:

if auth.HasCapability(handler.Capabilities(), auth.CapScopesOnTokenRequest) {
    // safe to pass per-request scopes
}

Related Documentation

• Authentication Design — architecture overview and design decisions
• Auth Tutorial — getting started guide
• Auth Handler Development — writing new handlers