verifier

Documentation

Overview

Package verifier provides multi-issuer JWT verification for lakta services.

A Registry holds one JWKS-backed verifier per configured issuer (keyed by the exact iss claim) plus an isolated HS256 static-key dev path, and exposes a single Verify entry point the fiber and grpc auth adapters call. Every verification failure surfaces as an opaque errors.Unauthenticated; the package never reveals which check failed.

Index

• func ContextWithPrincipal(ctx context.Context, p *Principal) context.Context
• type Config
  • func NewConfig(options ...Option) Config
  • func NewDefaultConfig() Config
  • func (c *Config) LoadFromKoanf(k *koanf.Koanf, path string) error
• type IssuerConfig
• type Module
  • func NewModule(options ...Option) *Module
  • func (m *Module) ConfigPath() string
  • func (m *Module) Dependencies() ([]reflect.Type, []reflect.Type)
  • func (m *Module) Init(ctx context.Context) error
  • func (m *Module) LoadConfig(k *koanf.Koanf) error
  • func (m *Module) OnReload(k *koanf.Koanf)
  • func (m *Module) Provides() []reflect.Type
  • func (m *Module) Shutdown(_ context.Context) error
• type Option
  • func WithName(name string) Option
• type Principal
  • func PrincipalFrom(ctx context.Context) (*Principal, bool)
  • func (p *Principal) HasRole(r string) bool
  • func (p *Principal) HasScope(s string) bool
• type Registry
  • func (r *Registry) Verify(_ context.Context, rawToken string) (*Principal, error)
• type StaticKey

Functions

func ContextWithPrincipal

func ContextWithPrincipal(ctx context.Context, p *Principal) context.Context

ContextWithPrincipal returns a child ctx carrying p.

Types

type Config

type Config struct {
	Name       string         `koanf:"-"`
	Issuers    []IssuerConfig `koanf:"issuers"`
	StaticKey  *StaticKey     `koanf:"static_key"`
	ScopeClaim string         `koanf:"scope_claim"`
	RolesClaim string         `koanf:"roles_claim"`
}

Config is unmarshaled from modules.auth.verifier.<instance>.

func NewConfig

func NewConfig(options ...Option) Config

NewConfig returns configuration with provided options based on defaults.

func NewDefaultConfig

func NewDefaultConfig() Config

NewDefaultConfig returns default configuration.

func (*Config) LoadFromKoanf

func (c *Config) LoadFromKoanf(k *koanf.Koanf, path string) error

LoadFromKoanf loads configuration from koanf instance at the given path.

type IssuerConfig

type IssuerConfig struct {
	// Issuer is matched against the token iss exactly (no prefix/substring).
	Issuer string `koanf:"issuer"`
	// Audience MUST be non-empty; the token aud must intersect it.
	Audience []string `koanf:"audience"`
	// JWKSURL is the JWKS endpoint; empty triggers OIDC discovery from Issuer.
	JWKSURL string `koanf:"jwks_url"`
	// Algorithms is a hard allowlist, e.g. [RS256, ES256]; alg:none is rejected.
	Algorithms []string `koanf:"algorithms"`
	// ClockSkew is capped at maxClockSkew.
	ClockSkew time.Duration `koanf:"clock_skew"`
}

IssuerConfig is one trusted JWKS/OIDC issuer.

type Module

type Module struct {
	// contains filtered or unexported fields
}

Module provides a *Registry at modules.auth.verifier.<instance> via DI.

func NewModule

func NewModule(options ...Option) *Module

NewModule creates a new auth verifier module.

func (*Module) ConfigPath

func (m *Module) ConfigPath() string

ConfigPath returns the koanf path for this module's configuration.

func (*Module) Dependencies

func (m *Module) Dependencies() ([]reflect.Type, []reflect.Type)

Dependencies declares the optional types this module needs from DI before Init.

func (*Module) Init

func (m *Module) Init(ctx context.Context) error

Init builds the Registry from config and provides it into DI.

func (*Module) LoadConfig

func (m *Module) LoadConfig(k *koanf.Koanf) error

LoadConfig loads configuration from koanf.

func (*Module) OnReload

func (m *Module) OnReload(k *koanf.Koanf)

OnReload rebuilds the verifiers only when issuers/audience/static_key (or the claim paths) change; JWKS rotation is already automatic via the cache.

func (*Module) Provides

func (m *Module) Provides() []reflect.Type

Provides returns the types this module registers in DI.

func (*Module) Shutdown

func (m *Module) Shutdown(_ context.Context) error

Shutdown stops the background JWKS refresh.

type Option

type Option func(*Config)

Option configures the Module.

func WithName

func WithName(name string) Option

WithName sets the instance name for this module.

type Principal

type Principal struct {
	Subject  string
	Issuer   string
	Audience []string
	Scopes   []string
	Roles    []string
	Claims   map[string]any
	Token    jwt.Token
}

Principal is the verified identity the adapters stash in the request context after a successful Registry.Verify.

func PrincipalFrom

func PrincipalFrom(ctx context.Context) (*Principal, bool)

PrincipalFrom returns the Principal placed in ctx by the adapters, and false when the request is anonymous.

func (*Principal) HasRole

func (p *Principal) HasRole(r string) bool

HasRole reports whether p holds role r.

func (*Principal) HasScope

func (p *Principal) HasScope(s string) bool

HasScope reports whether p holds scope s.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds one verifier per configured issuer plus the isolated static-key verifier. It is the single entry point both adapters call.

func (*Registry) Verify

func (r *Registry) Verify(_ context.Context, rawToken string) (*Principal, error)

Verify validates rawToken end-to-end and returns the Principal. Every failure path returns an opaque errors.Unauthenticated that never reveals which check failed. See the phase design for the numbered sequence.

type StaticKey

type StaticKey struct {
	Algorithm string   `koanf:"algorithm"`
	Secret    string   `koanf:"secret"`
	Profiles  []string `koanf:"profiles"`
}

StaticKey is the isolated HS256 dev path, allow-only under Profiles.