auth

Documentation

Overview

Package auth provides framework-agnostic JWT signing/parsing and password hashing for lagodev-based applications.

The Manager holds a signing secret plus TTL configuration and produces signed JWTs from Claims. Parse verifies the signature and expiry. The package returns ErrInvalidToken / ErrExpiredToken so callers can map them to HTTP responses without inspecting jwt-library error strings.

Password helpers wrap golang.org/x/crypto/bcrypt with the project's preferred cost so storage layers don't need to import bcrypt directly.

Index

• Constants
• Variables
• type Claims
• type Config
• type Manager
  • func New(cfg Config) (*Manager, error)
  • func (m *Manager) AccessTTL() time.Duration
  • func (m *Manager) HashPassword(password string) (string, error)
  • func (m *Manager) Issue(userID uint64, role, tokenType string, ttl time.Duration) (string, time.Time, error)
  • func (m *Manager) IssueAccess(userID uint64, role string) (string, time.Time, error)
  • func (m *Manager) IssueRefresh(userID uint64, role string) (string, time.Time, error)
  • func (m *Manager) Parse(token string) (*Claims, error)
  • func (m *Manager) RefreshTTL() time.Duration
  • func (m *Manager) VerifyPassword(hash, password string) bool

Constants

const (
	TokenAccess  = "access"
	TokenRefresh = "refresh"
)

Default token types — applications may define their own (e.g. "api").

Variables

var ErrExpiredToken = errors.New("auth: token expired")

ErrExpiredToken is returned when the token's exp claim is in the past.

var ErrInvalidToken = errors.New("auth: invalid token")

ErrInvalidToken is returned when the token is malformed, has a bad signature, or fails any of the registered validators.

Types

type Claims

type Claims struct {
	UserID uint64 `json:"uid"`
	Role   string `json:"role,omitempty"`
	Type   string `json:"typ,omitempty"`
	jwt.RegisteredClaims
}

Claims is the payload carried inside every JWT issued by Manager. Embed jwt.RegisteredClaims for iss/sub/exp/iat/nbf/jti.

type Config

type Config struct {
	Secret     string
	Issuer     string
	AccessTTL  time.Duration
	RefreshTTL time.Duration
	BcryptCost int
}

Config holds the signing secret and token lifetimes. Secret must be a strong random value (>=32 bytes). Issuer is optional and embedded into the iss claim when non-empty.

type Manager

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

Manager issues and verifies tokens.

func New

func New(cfg Config) (*Manager, error)

New returns a Manager. The secret must be non-empty.

func (*Manager) AccessTTL

func (m *Manager) AccessTTL() time.Duration

Config returns the manager's configuration (without copying the secret pointer).

func (*Manager) HashPassword

func (m *Manager) HashPassword(password string) (string, error)

HashPassword returns a bcrypt hash of the password using the configured cost.

func (*Manager) Issue

func (m *Manager) Issue(userID uint64, role, tokenType string, ttl time.Duration) (string, time.Time, error)

Issue signs a custom token type with a caller-specified TTL.

func (*Manager) IssueAccess

func (m *Manager) IssueAccess(userID uint64, role string) (string, time.Time, error)

IssueAccess signs an access token (short-lived) for the given user.

func (*Manager) IssueRefresh

func (m *Manager) IssueRefresh(userID uint64, role string) (string, time.Time, error)

IssueRefresh signs a refresh token (long-lived) for the given user.

func (*Manager) Parse

func (m *Manager) Parse(token string) (*Claims, error)

Parse verifies the token's signature and expiry. It returns the claims on success, or ErrInvalidToken / ErrExpiredToken on failure.

func (*Manager) RefreshTTL

func (m *Manager) RefreshTTL() time.Duration

func (*Manager) VerifyPassword

func (m *Manager) VerifyPassword(hash, password string) bool

VerifyPassword reports whether password matches the stored bcrypt hash.