auth

README

auth

The togo base auth provider: JWT token auth, bcrypt passwords, a self-contained users store (via the ORM), multi-guard, roles + permissions (RBAC), middleware, and /api/auth routes. Default driver for the framework; Supabase/Firebase/OAuth/WorkOS ship as driver plugins that depend on this package.

togo install togo-framework/auth

Documentation

Overview

Package auth is togo's base authentication system: JWT token auth, bcrypt passwords, a self-contained users store (via the ORM), multi-guard, and roles/permissions (RBAC). It's the default auth driver; Supabase/Firebase/ OAuth/WorkOS ship as driver plugins that depend on this package.

Install: `togo install togo-framework/auth` (blank-import registers it).

Index

• Constants
• Variables
• type Authenticator
• type Guard
• type Identity
  • func IdentityFrom(ctx context.Context) (*Identity, bool)
  • func (i Identity) Can(perm string) bool
  • func (i Identity) HasRole(role string) bool
• type Service
  • func FromKernel(k *togo.Kernel) (*Service, bool)
  • func New(k *togo.Kernel) (*Service, error)
  • func (s *Service) Guard(name string) *Guard
  • func (s *Service) IssueToken(id Identity) (string, error)
  • func (s *Service) Middleware(next http.Handler) http.Handler
  • func (s *Service) RegisterGuard(name string, a Authenticator)
  • func (s *Service) RequirePermission(perm string) func(http.Handler) http.Handler
  • func (s *Service) RequireRole(role string) func(http.Handler) http.Handler
  • func (s *Service) Verify(token string) (*Identity, error)
• type User

Constants

const (
	EventRegistered      = "auth.registered"
	EventLogin           = "auth.login"
	EventLogout          = "auth.logout"
	EventPasswordChanged = "auth.password_changed"
	EventLoginFailed     = "auth.login_failed"
)

Auth lifecycle events fired on the kernel hook bus. Apps subscribe via k.Hooks.On(auth.EventLogin, 50, fn) to inject behavior — audit logging, welcome mail, post-login/redirect decisions, etc. Listeners run in priority order.

const SessionCookie = "togo_session"

SessionCookie is the name of the HttpOnly cookie holding the session token.

Variables

var ErrInvalidCredentials = errors.New("invalid credentials")

ErrInvalidCredentials is returned when email/password don't match.

Types

type Authenticator

type Authenticator interface {
	Attempt(ctx context.Context, email, password string) (*Identity, error)
	ByID(ctx context.Context, id string) (*Identity, error)
}

Authenticator verifies credentials and loads identities. Drivers (supabase, oauth, …) implement this; the default is DB + bcrypt.

type Guard

type Guard struct {
	Name string
	Auth Authenticator
}

Guard pairs a name with an Authenticator — enabling multi-guard setups.

type Identity

type Identity struct {
	ID          string   `json:"id"`
	Email       string   `json:"email"`
	Roles       []string `json:"roles"`
	Permissions []string `json:"permissions"`
	Guard       string   `json:"guard"`
}

Identity is the authenticated principal exposed to the app.

func IdentityFrom

func IdentityFrom(ctx context.Context) (*Identity, bool)

IdentityFrom returns the authenticated identity from the request context.

func (Identity) Can

func (i Identity) Can(perm string) bool

Can reports whether the identity has a permission.

func (Identity) HasRole

func (i Identity) HasRole(role string) bool

HasRole reports whether the identity has a role.

type Service

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

Service is the auth runtime stored on the kernel (k.Get("auth")).

func FromKernel

func FromKernel(k *togo.Kernel) (*Service, bool)

FromKernel fetches the auth service from the kernel container.

func New

func New(k *togo.Kernel) (*Service, error)

New builds the service, ensures the users table exists, and registers the default DB-backed guard. It fails closed in production when no strong secret is configured.

func (*Service) Guard

func (s *Service) Guard(name string) *Guard

Guard returns a named guard (or the default).

func (*Service) IssueToken

func (s *Service) IssueToken(id Identity) (string, error)

IssueToken signs a JWT for an identity.

func (*Service) Middleware

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

Middleware authenticates the request from its bearer token and stores the Identity in context. 401 if the token is missing/invalid.

func (*Service) RegisterGuard

func (s *Service) RegisterGuard(name string, a Authenticator)

RegisterGuard adds a named guard (multi-guard support).

func (*Service) RequirePermission

func (s *Service) RequirePermission(perm string) func(http.Handler) http.Handler

RequirePermission guards a route by permission.

func (*Service) RequireRole

func (s *Service) RequireRole(role string) func(http.Handler) http.Handler

RequireRole guards a route by role.

func (*Service) Verify

func (s *Service) Verify(token string) (*Identity, error)

Verify parses a token into an Identity. Enforces HS256, a required expiry, and the issuer — rejecting alg-confusion, unexpiring, and foreign tokens.

type User

type User struct {
	ID           string `db:"id" json:"id"`
	Email        string `db:"email" json:"email"`
	PasswordHash string `db:"password_hash" json:"-"`
	Roles        string `db:"roles" json:"roles"`
	Permissions  string `db:"permissions" json:"permissions"`
	CreatedAt    string `db:"created_at" json:"created_at"`
}

User is the stored account. All columns are TEXT for cross-driver portability.