auth

Documentation

Index

• Variables
• type Claims
  • func ValidateToken(cfg Config, tokenStr string) (*Claims, error)
• type Config
  • func DefaultConfig(jwtSecret string, superAdminEmail string) Config
• type Group
• type Mailer
• type MigrationRecord
• type Migrator
• type OTP
• type Permission
• type Store
• type TokenPair
  • func GenerateTokenPair(cfg Config, user *User, permissions []string, groups []string) (*TokenPair, error)
• type User

Variables

var (
	ErrOTPExpired         = errors.New("auth: otp has expired")
	ErrOTPInvalid         = errors.New("auth: invalid otp code")
	ErrUserNotFound       = errors.New("auth: user not found")
	ErrPermissionNotFound = errors.New("auth: permission not found")
	ErrPermissionExists   = errors.New("auth: permission already exists")
	ErrGroupNotFound      = errors.New("auth: group not found")
	ErrGroupExists        = errors.New("auth: group already exists")
)

Types

type Claims

type Claims struct {
	UserID      string   `json:"user_id"`
	Email       string   `json:"email"`
	Type        string   `json:"type"` // "access" or "refresh"
	Permissions []string `json:"permissions,omitempty"`
	Groups      []string `json:"groups,omitempty"` // group names
}

Claims represents the JWT token claims.

func ValidateToken

func ValidateToken(cfg Config, tokenStr string) (*Claims, error)

ValidateToken parses and validates a JWT token, returning the claims.

type Config

type Config struct {
	JWTSecret       string
	OTPLength       int
	OTPExpiry       time.Duration
	AccessExpiry    time.Duration
	RefreshExpiry   time.Duration
	SuperAdminEmail string
	AutoMigrate     bool // if true, Bootstrap() runs migrations automatically
}

Config holds the configuration for the auth package.

func DefaultConfig

func DefaultConfig(jwtSecret string, superAdminEmail string) Config

DefaultConfig returns a Config with sensible defaults.

type Group

type Group struct {
	ID          string       `json:"id"`
	Name        string       `json:"name"` // e.g. "Editor"
	Permissions []Permission `json:"permissions,omitempty"`
	CreatedAt   time.Time    `json:"created_at"`
}

Group represents a permission group for bulk assignment.

type Mailer

type Mailer interface {
	SendOTP(ctx context.Context, email string, code string, expiresIn time.Duration) error
}

Mailer defines the contract for sending OTP emails.

type MigrationRecord

type MigrationRecord struct {
	Name      string
	Applied   bool
	AppliedAt *time.Time
	Checksum  string
}

MigrationRecord represents an applied database migration.

type Migrator

type Migrator interface {
	// Migrate applies all pending migrations in order.
	Migrate(ctx context.Context) error

	// Rollback rolls back the last applied migration.
	Rollback(ctx context.Context) error

	// MigrationStatus returns all migrations with their applied status.
	MigrationStatus(ctx context.Context) ([]MigrationRecord, error)
}

Migrator defines the contract for managing database migrations.

type OTP

type OTP struct {
	ID        string    `json:"id"`
	Email     string    `json:"email"`
	Code      string    `json:"code"`
	ExpiresAt time.Time `json:"expires_at"`
	Verified  bool      `json:"verified"`
	CreatedAt time.Time `json:"created_at"`
}

OTP represents a one-time password sent to a user's email.

type Permission

type Permission struct {
	ID          string    `json:"id"`
	Key         string    `json:"key"`         // e.g. "forms:create"
	Description string    `json:"description"` // e.g. "Can create forms"
	CreatedAt   time.Time `json:"created_at"`
}

Permission represents a single permission that can be assigned to users or groups.

type Store

type Store interface {
	// Schema
	CreateSchema(ctx context.Context) error
	DropSchema(ctx context.Context) error

	// OTP
	CreateOTP(ctx context.Context, email string) (*OTP, error)
	VerifyOTP(ctx context.Context, email string, code string) (*User, error)

	// Users
	CreateUser(ctx context.Context, email string) (*User, error)
	GetUserByID(ctx context.Context, id string) (*User, error)
	GetUserByEmail(ctx context.Context, email string) (*User, error)
	ListUsers(ctx context.Context) ([]User, error)

	// Permissions
	CreatePermission(ctx context.Context, key string, description string) (*Permission, error)
	GetPermission(ctx context.Context, key string) (*Permission, error)
	ListPermissions(ctx context.Context) ([]Permission, error)
	DeletePermission(ctx context.Context, id string) error

	// User Permissions (direct)
	AssignPermission(ctx context.Context, userID string, permissionKey string) error
	RevokePermission(ctx context.Context, userID string, permissionKey string) error
	GetUserPermissions(ctx context.Context, userID string) ([]Permission, error)
	HasPermission(ctx context.Context, userID string, permissionKey string) (bool, error)

	// Groups
	CreateGroup(ctx context.Context, name string) (*Group, error)
	GetGroup(ctx context.Context, id string) (*Group, error)
	ListGroups(ctx context.Context) ([]Group, error)
	DeleteGroup(ctx context.Context, id string) error
	AddPermissionToGroup(ctx context.Context, groupID string, permissionKey string) error
	RemovePermissionFromGroup(ctx context.Context, groupID string, permissionID string) error

	// User Groups
	AssignUserToGroup(ctx context.Context, userID string, groupID string) error
	RemoveUserFromGroup(ctx context.Context, userID string, groupID string) error
	GetUserGroups(ctx context.Context, userID string) ([]Group, error)

	// Resolved Permissions (direct + from groups)
	GetResolvedPermissions(ctx context.Context, userID string) ([]Permission, error)
	HasResolvedPermission(ctx context.Context, userID string, permissionKey string) (bool, error)

	// Bootstrap
	Bootstrap(ctx context.Context, superAdminEmail string) error
}

Store defines the contract for persisting and retrieving auth data.

type TokenPair

type TokenPair struct {
	AccessToken  string `json:"access_token"`
	RefreshToken string `json:"refresh_token"`
}

TokenPair holds the JWT access and refresh tokens.

func GenerateTokenPair

func GenerateTokenPair(cfg Config, user *User, permissions []string, groups []string) (*TokenPair, error)

GenerateTokenPair creates a signed access token and refresh token for the given user with embedded permissions and groups.

type User

type User struct {
	ID        string    `json:"id"`
	Email     string    `json:"email"`
	CreatedAt time.Time `json:"created_at"`
}

User represents an authenticated user.