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 (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) ParseAccess(token string) (*Claims, error)
- func (m *Manager) ParseRefresh(token string) (*Claims, error)
- func (m *Manager) ParseTyped(token, expectedType 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").
const DefaultLeeway = 30 * time.Second
DefaultLeeway is the clock-skew tolerance applied when Config.Leeway is zero.
const MinSecretLen = 32
MinSecretLen is the minimum byte length enforced for Config.Secret unless AllowWeakSecret is set.
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.
Functions ¶
This section is empty.
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
Audience string
AccessTTL time.Duration
RefreshTTL time.Duration
BcryptCost int
// Leeway is the clock-skew tolerance applied to exp/nbf/iat validation.
// Defaults to 30s when zero.
Leeway time.Duration
// AllowWeakSecret skips the >=32 byte secret length check in New. Only
// set this in tests or when the secret strength is guaranteed elsewhere.
AllowWeakSecret bool
}
Config holds the signing secret and token lifetimes. Secret must be a strong random value (>=32 bytes by default; relax with AllowWeakSecret). Issuer is optional and embedded into the iss claim when non-empty; when set it is also verified on Parse. Audience is optional; when set it is embedded into the aud claim and verified on Parse.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager issues and verifies tokens.
func New ¶
New returns a Manager. The secret must be non-empty and at least MinSecretLen bytes (unless cfg.AllowWeakSecret is set).
func (*Manager) HashPassword ¶
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 ¶
IssueAccess signs an access token (short-lived) for the given user.
func (*Manager) IssueRefresh ¶
IssueRefresh signs a refresh token (long-lived) for the given user.
func (*Manager) Parse ¶
Parse verifies the token's signature, expiry, issuer/audience (when configured), and applies the configured clock-skew leeway. It returns the claims on success, or ErrInvalidToken / ErrExpiredToken on failure.
func (*Manager) ParseAccess ¶ added in v0.20.0
ParseAccess parses token and asserts it is an access token (Type == TokenAccess).
func (*Manager) ParseRefresh ¶ added in v0.20.0
ParseRefresh parses token and asserts it is a refresh token (Type == TokenRefresh).
func (*Manager) ParseTyped ¶ added in v0.20.0
ParseTyped is Parse plus an assertion that the token's Type claim equals expected. It returns ErrInvalidToken when the type does not match, so an access token cannot be replayed where a refresh token is required (and vice versa).
func (*Manager) RefreshTTL ¶
RefreshTTL returns the configured refresh-token lifetime.
func (*Manager) VerifyPassword ¶
VerifyPassword reports whether password matches the stored bcrypt hash.
Source Files