auth

Documentation

Overview

Package auth implements Epic 9 browser sessions, local login, hashed API keys, and an OIDC bridge over the DB-backed user model.

Index

• Variables
• type Options
• type Principal
  • func PrincipalFromContext(ctx context.Context) (Principal, bool)
  • func (principal Principal) HasAPIKeyCapability(capability store.APIKeyCapability) bool
• type Service
  • func New(ctx context.Context, options Options) (*Service, error)
  • func (s *Service) Authenticate(r *http.Request) (Principal, error)
  • func (s *Service) Handler() http.Handler
  • func (s *Service) Identify(next http.Handler) http.Handler
  • func (s *Service) LoadAndSave(next http.Handler) http.Handler
  • func (s *Service) Require(next http.Handler) http.Handler
  • func (s *Service) SetupToken() string

Variables

var (
	ErrUnauthenticated = errors.New("authentication required")
	ErrInvalidCSRF     = errors.New("invalid CSRF token")
)

Types

type Options

type Options struct {
	Config     config.Auth
	Store      store.AuthStore
	HTTPClient *http.Client
	Now        func() time.Time
	// ArgonConcurrency bounds memory-hard password work. Zero selects the
	// production default of four concurrent hashes.
	ArgonConcurrency int
	// Audit records authentication and key-lifecycle events (T10.1). Nil
	// disables recording; failures inside the callback must not fail requests.
	Audit func(ctx context.Context, event store.AuditEvent)
}

Options contains the dependencies required by the cohesive auth HTTP surface. HTTPClient is optional and primarily supports private CAs/test IdPs.

type Principal

type Principal struct {
	User               *store.User
	APIKeyID           string
	APIKeyCapabilities []store.APIKeyCapability
	AuthMethod         string
	IsAdmin            bool
}

Principal is attached to authenticated request contexts. User is nil only for the migration-only auth.api_key principal.

func PrincipalFromContext

func PrincipalFromContext(ctx context.Context) (Principal, bool)

PrincipalFromContext returns the identity established by Require.

func (Principal) HasAPIKeyCapability

func (principal Principal) HasAPIKeyCapability(capability store.APIKeyCapability) bool

HasAPIKeyCapability reports authority carried by the authenticated named bearer key. Browser sessions and the migration-only legacy key never emulate a bearer capability.

type Service

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

Service is safe for concurrent HTTP use.

func New

func New(ctx context.Context, options Options) (*Service, error)

func (*Service) Authenticate

func (s *Service) Authenticate(r *http.Request) (Principal, error)

Authenticate accepts either one Bearer API key or the SCS browser session. An explicitly malformed/invalid Authorization header never falls back to a cookie, preventing ambiguous credential selection.

func (*Service) Handler

func (s *Service) Handler() http.Handler

Handler exposes the complete Epic 9 auth route set. It must be mounted beneath LoadAndSave so SCS has loaded request context before a route runs.

func (*Service) Identify

func (s *Service) Identify(next http.Handler) http.Handler

Identify attaches a principal when the request authenticates successfully, but preserves public access when it does not. It is intentionally narrower than Require: public handlers must still decide which response fields are safe without a principal, and invalid credentials never reveal protected state through a distinguishable response.

func (*Service) LoadAndSave

func (s *Service) LoadAndSave(next http.Handler) http.Handler

LoadAndSave must wrap the top-level mux so sessions established on the auth routes are available to protected API and MCP handlers too.

func (*Service) Require

func (s *Service) Require(next http.Handler) http.Handler

Require establishes a Principal and enforces CSRF on unsafe browser-session requests. Bearer clients are not vulnerable to ambient-cookie CSRF.

func (*Service) SetupToken

func (s *Service) SetupToken() string

SetupToken returns the ephemeral token required by POST /api/auth/setup. The caller should log it to the local operator once; it is cleared after the first user is created and is never persisted.