core

Documentation

Index

• Variables
• type Account
• type AccountStorage
• type AuthProvider
• type Cache
• type CacheConfig
• type CacheStats
• type CacheWithStats
• type CreateSessionResult
• type Endpoint
• type EndpointMetadata
• type EndpointProvider
• type ErrorResponse
• type HTTPProvider
• type RefreshResult
• type RequestContext
• type Session
• type SessionConfig
• type SessionData
• type SessionStorage
• type SignInInput
• type SignInResult
• type SignUpInput
• type SignUpResult
• type StorageProvider
• type User
• type UserStorage

Variables

var (
	// User errors
	ErrUserExists         = errors.New("user already exists")       // 409 Conflict
	ErrUserNotFound       = errors.New("user not found")            // 404 Not Found
	ErrInvalidCredentials = errors.New("invalid email or password") // 401 Unauthorized
)

Authentication Related Errors

var (
	ErrMissingAuthHeader = errors.New("missing authorization header") // 401
	ErrInvalidToken      = errors.New("invalid session token")        // 401
	ErrSessionNotFound   = errors.New("session not found")            // 401
	ErrSessionExpired    = errors.New("session expired")              // 401
	ErrCacheNotFound     = errors.New("session not found in cache")
)

Session errors

var (
	ErrInvalidAuthHeader = errors.New("invalid authorization format, expected 'Bearer <token>'") // 401
	ErrEmailRequired     = errors.New("email is required")                                       // 400
	ErrPasswordRequired  = errors.New("password is required")                                    // 400
	ErrPasswordTooShort  = errors.New("password is too short")                                   // 400
	ErrPasswordTooLong   = errors.New("password is too long")                                    // 400
	ErrInvalidEmail      = errors.New("invalid email format")                                    // 400
)

Validation errors (client input)

var (
	ErrDBAdapterRequired   = errors.New("database adapter is required") // 500
	ErrHTTPAdapterRequired = errors.New("adapter is required")          // 500
	ErrSecretRequired      = errors.New("secret is required")           // 500
	ErrSecretTooShort      = errors.New("secret too short")             // 500
)

Config errors (server-side configuration)

var (
	ErrNotImplemented = errors.New("not implemented") // 501
)

Types

type Account

type Account struct {
	ID           string     `json:"id"`
	UserID       string     `json:"userId"`
	ProviderID   string     `json:"providerId"` // "credential", "google", "github"
	AccountID    string     `json:"accountId"`
	Password     *string    `json:"-"` // Never expose in JSON
	AccessToken  *string    `json:"-"` // Never expose in JSON
	RefreshToken *string    `json:"-"` // Never expose in JSON
	ExpiresAt    *time.Time `json:"expiresAt,omitempty"`
	CreatedAt    time.Time  `json:"createdAt"`
	UpdatedAt    time.Time  `json:"updatedAt"`
}

Account represents an authentication method

This is the "credential" - how someone proves who they are

type AccountStorage

type AccountStorage interface {
	CreateAccount(a *Account) error
	GetAccountByID(id string) (*Account, error)
	GetAccountByUserAndProvider(userID, providerID string) ([]*Account, error)
	UpdateAccount(a *Account) error
	DeleteAccount(id string) error
}

AccountStorage defines account-related database operations

type AuthProvider

type AuthProvider interface {
	SignUp(input SignUpInput, ipAddress, userAgent string) (*SignUpResult, error)
	SignIn(input SignInInput, ipAddress, userAgent string) (*SignInResult, error)
	SignOut(token string) error
	GetSession(token string) (*SessionData, error)
	Refresh(token string) (*RefreshResult, error)
}

AuthProvider provides authentication operations for HTTP adapters

type Cache

type Cache interface {
	Get(tokenHash string) (*Session, error)
	Set(tokenHash string, session *Session) error
	Delete(tokenHash string) error
	Clear() error
}

Cache defines session caching operations

type CacheConfig

type CacheConfig struct {
	TTL     time.Duration
	MaxSize int
}

CacheConfig configures cache behavior

type CacheStats

type CacheStats struct {
	Hits      int64         `json:"hits"`
	Misses    int64         `json:"misses"`
	Sets      int64         `json:"sets"`
	Deletes   int64         `json:"deletes"`
	Evictions int64         `json:"evictions"`
	Size      int           `json:"size"`
	TTL       time.Duration `json:"ttl"`
}

CacheStats tracks cache performance metrics

type CacheWithStats

type CacheWithStats interface {
	Cache
	Stats() CacheStats
}

CacheWithStats extends Cache with statistics tracking

type CreateSessionResult

type CreateSessionResult struct {
	Session *Session `json:"session"`
	Token   string   `json:"token"`
}

type Endpoint

type Endpoint struct {
	Path     string
	Method   string
	Handler  func(ctx *RequestContext) error
	Metadata EndpointMetadata
}

type EndpointMetadata

type EndpointMetadata struct {
	OperationID string
	Description string
	RequestBody interface{} // for validation
	Responses   map[int]interface{}
}

type EndpointProvider

type EndpointProvider interface {
	GetEndpoints() []Endpoint
}

EndpointProvider provides a list of endpoints to register dynamically

type ErrorResponse

type ErrorResponse struct {
	Error   string `json:"error"`
	Message string `json:"message,omitempty"`
	Code    int    `json:"code,omitempty"`
}

ErrorResponse represents an error response structure

type HTTPProvider

type HTTPProvider interface {
	RegisterRoutes(handler AuthProvider, basePath string, ttl time.Duration) error
	BuildProtectedMiddleware(authProvider AuthProvider) interface{}
}

type RefreshResult

type RefreshResult struct {
	Session *Session `json:"session"`
	Token   string   `json:"token"` // The raw token (not the hash)
}

type RequestContext

type RequestContext struct {
	// Framework-agnostic context
	Request interface{} // could be *http.Request, fiber.Ctx, etc
	Auth    AuthProvider
}

type Session

type Session struct {
	ID        string    `json:"id"`
	UserID    string    `json:"userId"`
	TokenHash string    `json:"-"` // Never expose in JSON (security!)
	IPAddress string    `json:"ipAddress"`
	UserAgent string    `json:"userAgent"`
	ExpiresAt time.Time `json:"expiresAt"`
	CreatedAt time.Time `json:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt"`
}

Session represents an active login session

type SessionConfig

type SessionConfig struct {
	MaxAge time.Duration
}

type SessionData

type SessionData struct {
	User    *User    `json:"user"`
	Session *Session `json:"session"`
}

SessionData combines user and session info The model returned to clients

type SessionStorage

type SessionStorage interface {
	CreateSession(session *Session) error
	GetSessionByHash(tokenHash string) (*Session, error)
	GetSessionByID(id string) (*Session, error)
	GetUserSessions(userID string) ([]*Session, error)
	UpdateSession(session *Session) error
	DeleteSessionByID(id string) error
	DeleteSessionByHash(tokenHash string) error
	DeleteUserSessions(userID string) (int, error)
	DeleteExpiredSessions() (int, error)
}

SessionStorage defines session-related database operations

type SignInInput

type SignInInput struct {
	Email    string
	Password string
}

type SignInResult

type SignInResult struct {
	User    *User    `json:"user"`
	Session *Session `json:"session"`
	Token   string   `json:"token"` // The raw token (not the hash)
}

type SignUpInput

type SignUpInput struct {
	Email    string
	Password string
	Name     string
	Image    *string
}

type SignUpResult

type SignUpResult struct {
	User    *User    `json:"user"`
	Session *Session `json:"session"`
	Token   string   `json:"token"` // The raw token (not the hash)
}

type StorageProvider

type StorageProvider interface {
	UserStorage
	AccountStorage
	SessionStorage
}

type User

type User struct {
	ID            string    `json:"id"`
	Email         string    `json:"email"`
	EmailVerified bool      `json:"emailVerified"`
	Name          string    `json:"name"`
	Image         *string   `json:"image,omitempty"`
	CreatedAt     time.Time `json:"createdAt"`
	UpdatedAt     time.Time `json:"updatedAt"`
}

User represents a user account in the system

This is the "identity" - who someone is

type UserStorage

type UserStorage interface {
	CreateUser(u *User) error
	GetUserByID(id string) (*User, error)
	GetUserByEmail(email string) (*User, error)
	UpdateUser(u *User) error
	DeleteUser(id string) error
}

UserStorage defines user-related database operations