Documentation
¶
Overview ¶
Package account provides a ready-to-use user module with registration, login, token refresh, and password management.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Module ¶
type Module struct {
// contains filtered or unexported fields
}
Module manages user accounts.
func Setup ¶
func Setup(gdb *gorm.DB, logger log.Logger, opts *config.AccountOptions, r RouteGroup, modOpts ...Option) (*Module, error)
Setup creates the account module from config, migrates the User table, and registers routes — all in one call.
Returns (nil, nil) if opts is nil or opts.Enabled is false. Extra modOpts (e.g. WithSender) are applied on top of config values.
acct, err := account.Setup(gdb, logger, &cfg.Account, srv.Group("/auth"))
func (*Module) ActiveCheck ¶
func (m *Module) ActiveCheck() gin.HandlerFunc
ActiveCheck returns a gin middleware that verifies the authenticated user still exists and is active by hitting the database on every request.
PrincipalResolver is stateless by design (no DB per request). Apply ActiveCheck to routes where real-time revocation matters:
api := srv.Group("/api/v1")
api.Use(middleware.Authn(acct.TokenParser(), acct.PrincipalResolver()))
api.Use(acct.ActiveCheck())
func (*Module) Close ¶
Close releases the module's background resources. The login rate limiter spawns short-lived cleanup goroutines on every Nth failure; Close waits for any in-flight cleanup so the App's shutdown budget covers them rather than leaving the goroutine running until the process terminates. Safe to call multiple times.
func (*Module) LoginRateLimitEnabled ¶
LoginRateLimitEnabled reports whether per-email login throttling is active. Useful for diagnostics, /healthz reporting, and tests that need to confirm a builder propagated the LoginRateWindow / LoginRateLimit configuration without poking at internal state.
func (*Module) PrincipalResolver ¶
func (m *Module) PrincipalResolver() middleware.PrincipalResolver
PrincipalResolver returns a resolver that builds a Principal from JWT claims. Roles are read from the "roles" claim in the token — no DB lookup required.
func (*Module) RegisterRoutes ¶
func (m *Module) RegisterRoutes(r RouteGroup)
RegisterRoutes registers account API routes on the given router.
Public routes (no auth required):
POST /register POST /login POST /forgot-password (only if WithSender is configured) POST /reset-password (only if WithSender is configured)
Authenticated routes:
POST /refresh-token PUT /change-password
func (*Module) TokenParser ¶
func (m *Module) TokenParser() middleware.TokenParser
TokenParser returns the JWT manager for use with middleware.Authn.
type Option ¶
type Option func(*moduleConfig)
Option configures a Module.
func WithExpiration ¶
WithExpiration sets the access token lifetime. Defaults to 2 hours.
func WithLoginRateLimit ¶
WithLoginRateLimit enables per-email login attempt rate limiting. When the threshold is exceeded within the window, the login endpoint returns 429 Too Many Requests. Defaults to disabled (zero values).
Recommended production values: window=15m, maxAttempts=10.
func WithResetExpiration ¶
WithResetExpiration sets the password-reset token lifetime. Defaults to 15 minutes.
func WithSender ¶
WithSender enables the forgot/reset-password flow.
func WithSigningKey ¶
WithSigningKey sets the JWT signing key (required, >= 32 bytes).
type RouteGroup ¶
type RouteGroup interface {
POST(string, ...gin.HandlerFunc) gin.IRoutes
PUT(string, ...gin.HandlerFunc) gin.IRoutes
Group(string, ...gin.HandlerFunc) *gin.RouterGroup
}
RouteGroup is the minimal interface for registering routes. *gin.RouterGroup satisfies this (use srv.Group("/path") to obtain one).
type Sender ¶
Sender delivers a password-reset code to the user (email, SMS, etc.). The module does not impose a delivery mechanism — callers provide their own.
type User ¶
type User struct {
db.SoftDeleteModel
Email string `json:"email" gorm:"size:200;not null"`
PasswordHash string `json:"-" gorm:"column:password_hash;size:128;not null"`
PasswordVersion int `json:"-" gorm:"column:password_version;default:0;not null"`
Name string `json:"name" gorm:"size:100;default:'';not null"`
Roles string `json:"-" gorm:"column:roles;size:500;default:'';not null"`
Active bool `json:"-" gorm:"default:true;not null"`
}
User is the built-in user model for the account module.