user

README

tinywasm/user

User management library for the tinywasm ecosystem. Handles user entities, password authentication, OAuth providers (Google, Microsoft), LAN (local network) authentication by RUT + IP, and session management. Applications import tinywasm/user directly to configure session behaviour and register isomorphic UI modules into tinywasm/site.

Documentation

• docs/ARCHITECTURE.md — What & Why: schema, contracts, design principles
• docs/IMPLEMENTATION.md — How: file layout, reference code, test strategy

Diagrams

• docs/diagrams/AUTH_FLOW.md — Local login credential validation
• docs/diagrams/SESSION_FLOW.md — Session lifecycle
• docs/diagrams/USER_CRUD_FLOW.md — User creation pipeline
• docs/diagrams/OAUTH_FLOW.md — OAuth begin/callback flow (all branches)
• docs/diagrams/LAN_AUTH_FLOW.md — LAN login: RUT validation + IP allowlist check
• docs/diagrams/LAN_IP_FLOW.md — LAN IP management: RegisterLAN, AssignLANIP, RevokeLANIP, GetLANIPs, UnregisterLAN

Integration

// main.go — application setup

// 1. Configure site (DB shared with user via applyUser internally)
site.SetDB(db)
site.SetUserID(extractUserID)    // reads session cookie, calls user.GetSession
site.CreateRole('a', "Admin", "full access")

// 2. Configure user via Config struct (all optional, zero values = defaults)
site.SetUserConfig(user.Config{
    SessionCookieName: "s",           // default: "session"
    SessionTTL:        86400,         // default: 86400 (24h)
    TrustProxy:        true,          // default: false
    OAuthProviders: []user.OAuthProvider{
        &user.GoogleProvider{
            ClientID:     os.Getenv("GOOGLE_CLIENT_ID"),
            ClientSecret: os.Getenv("GOOGLE_CLIENT_SECRET"),
            RedirectURL:  "https://example.com/oauth/callback",
        },
    },
})

// 3. Register user modules alongside app modules
site.RegisterHandlers(
    user.LoginModule,     // /login    — handles auth end-to-end (validate → login → session → cookie)
    user.RegisterModule,  // /register
    user.ProfileModule,   // /profile
    user.LANModule,       // /lan
    user.OAuthCallback,   // /oauth/callback
    &myapp.Dashboard{},
)

site.Serve(":8080")
// site.Serve internally calls:  applyUser() → user.Init(dbExecutor, cfg)
//                                applyRBAC() → rbac.Init(dbExecutor)

// After user registration/OAuth, assign default role:
// site.AssignRole(u.ID, 'v')  // rbac — completely independent of user lib

Status

Implementation pending. Documentation complete.

Documentation

Index

• Variables
• func AssignLANIP(userID, ip, label string) error
• func BeginOAuth(providerName string) (string, error)
• func CreateIdentity(userID, provider, providerID, email string) error
• func DeleteSession(id string) error
• func Init(exec Executor, cfg Config) error
• func PurgeExpiredOAuthStates() error
• func PurgeExpiredSessions() error
• func ReactivateUser(id string) error
• func RegisterLAN(userID, rut string) error
• func RevokeLANIP(userID, ip string) error
• func SessionCookieName() string
• func SetPassword(userID, password string) error
• func SuspendUser(id string) error
• func UnlinkIdentity(userID, provider string) error
• func UnregisterLAN(userID string) error
• func UpdateUser(id, name, phone string) error
• func VerifyPassword(userID, password string) error
• type Config
• type Executor
• type GoogleProvider
  • func (p *GoogleProvider) AuthCodeURL(state string) string
  • func (p *GoogleProvider) ExchangeCode(ctx context.Context, code string) (*oauth2.Token, error)
  • func (p *GoogleProvider) GetUserInfo(ctx context.Context, token *oauth2.Token) (OAuthUserInfo, error)
  • func (p *GoogleProvider) Name() string
• type Identity
  • func GetIdentityByProvider(provider, providerID string) (Identity, error)
  • func GetUserIdentities(userID string) ([]Identity, error)
• type LANIP
  • func GetLANIPs(userID string) ([]LANIP, error)
• type LoginData
• type MicrosoftProvider
  • func (p *MicrosoftProvider) AuthCodeURL(state string) string
  • func (p *MicrosoftProvider) ExchangeCode(ctx context.Context, code string) (*oauth2.Token, error)
  • func (p *MicrosoftProvider) GetUserInfo(ctx context.Context, token *oauth2.Token) (OAuthUserInfo, error)
  • func (p *MicrosoftProvider) Name() string
• type OAuthProvider
• type OAuthUserInfo
• type PasswordData
• type ProfileData
• type RegisterData
• type Rows
• type Scanner
• type Session
  • func CreateSession(userID, ip, userAgent string) (Session, error)
  • func GetSession(id string) (Session, error)
• type Store
• type User
  • func CompleteOAuth(providerName string, r *http.Request, ip, ua string) (User, bool, error)
  • func CreateUser(email, name, phone string) (User, error)
  • func GetUser(id string) (User, error)
  • func GetUserByEmail(email string) (User, error)
  • func Login(email, password string) (User, error)
  • func LoginLAN(rut string, r *http.Request) (User, error)

Variables

var (
	LoginModule    *loginModule
	RegisterModule *registerModule
	ProfileModule  *profileModule
	LANModule      *lanModule
	OAuthCallback  *oauthModule
)

var (
	ErrInvalidCredentials = fmt.Err("access", "denied")             // EN: Access Denied                    / ES: Acceso Denegado
	ErrSuspended          = fmt.Err("user", "suspended")            // EN: User Suspended                   / ES: Usuario Suspendido
	ErrEmailTaken         = fmt.Err("email", "registered")          // EN: Email Registered                 / ES: Correo electrónico Registrado
	ErrWeakPassword       = fmt.Err("password", "weak")             // EN: Password Weak                    / ES: Contraseña Débil
	ErrSessionExpired     = fmt.Err("token", "expired")             // EN: Token Expired                    / ES: Token Expirado
	ErrNotFound           = fmt.Err("user", "not", "found")         // EN: User Not Found                   / ES: Usuario No Encontrado
	ErrProviderNotFound   = fmt.Err("provider", "not", "found")     // EN: Provider Not Found               / ES: Proveedor No Encontrado
	ErrInvalidOAuthState  = fmt.Err("state", "invalid")             // EN: State Invalid                    / ES: Estado Inválido
	ErrCannotUnlink       = fmt.Err("identity", "cannot", "unlink") // EN: Identity Cannot Unlink           / ES: Identidad No puede Desvincular
	ErrInvalidRUT         = fmt.Err("rut", "invalid")               // EN: Rut Invalid                      / ES: Rut Inválido
	ErrRUTTaken           = fmt.Err("rut", "registered")            // EN: Rut Registered                   / ES: Rut Registrado
	ErrIPTaken            = fmt.Err("ip", "registered")             // EN: Ip Registered                    / ES: Ip Registrado
)

var PasswordHashCost = bcrypt.DefaultCost

Functions

func AssignLANIP

func AssignLANIP(userID, ip, label string) error

func BeginOAuth

func BeginOAuth(providerName string) (string, error)

func CreateIdentity

func CreateIdentity(userID, provider, providerID, email string) error

func DeleteSession

func DeleteSession(id string) error

func Init

func Init(exec Executor, cfg Config) error

func PurgeExpiredOAuthStates

func PurgeExpiredOAuthStates() error

func PurgeExpiredSessions

func PurgeExpiredSessions() error

func ReactivateUser

func ReactivateUser(id string) error

func RegisterLAN

func RegisterLAN(userID, rut string) error

func RevokeLANIP

func RevokeLANIP(userID, ip string) error

func SessionCookieName

func SessionCookieName() string

func SetPassword

func SetPassword(userID, password string) error

func SuspendUser

func SuspendUser(id string) error

func UnlinkIdentity

func UnlinkIdentity(userID, provider string) error

func UnregisterLAN

func UnregisterLAN(userID string) error

func UpdateUser

func UpdateUser(id, name, phone string) error

func VerifyPassword

func VerifyPassword(userID, password string) error

Types

type Config

type Config struct {
	SessionCookieName string // default: "session"
	SessionTTL        int    // default: 86400 (24h)
	TrustProxy        bool   // default: false
	OAuthProviders    []OAuthProvider
}

type Executor

type Executor interface {
	Exec(query string, args ...any) error
	Query(query string, args ...any) (Rows, error)
	QueryRow(query string, args ...any) Scanner
	Prepare(query string) (*sql.Stmt, error)
	Begin() (*sql.Tx, error)
}

Executor interface abstracts database operations.

type GoogleProvider

type GoogleProvider struct {
	ClientID     string
	ClientSecret string
	RedirectURL  string
	// contains filtered or unexported fields
}

func (*GoogleProvider) AuthCodeURL

func (p *GoogleProvider) AuthCodeURL(state string) string

func (*GoogleProvider) ExchangeCode

func (p *GoogleProvider) ExchangeCode(ctx context.Context, code string) (*oauth2.Token, error)

func (*GoogleProvider) GetUserInfo

func (p *GoogleProvider) GetUserInfo(ctx context.Context, token *oauth2.Token) (OAuthUserInfo, error)

func (*GoogleProvider) Name

func (p *GoogleProvider) Name() string

type Identity

type Identity struct {
	ID         string `json:"id"`
	UserID     string `json:"user_id"`
	Provider   string `json:"provider"`
	ProviderID string `json:"provider_id"`
	Email      string `json:"email,omitempty"`
	CreatedAt  int64  `json:"created_at"`
}

func GetIdentityByProvider

func GetIdentityByProvider(provider, providerID string) (Identity, error)

func GetUserIdentities

func GetUserIdentities(userID string) ([]Identity, error)

type LANIP

type LANIP struct {
	ID        string
	UserID    string
	IP        string
	Label     string
	CreatedAt int64
}

func GetLANIPs

func GetLANIPs(userID string) ([]LANIP, error)

type LoginData

type LoginData struct {
	Email    string
	Password string
}

LoginData is validated by LoginModule on both frontend and backend.

type MicrosoftProvider

type MicrosoftProvider struct {
	ClientID     string
	ClientSecret string
	RedirectURL  string
	// contains filtered or unexported fields
}

func (*MicrosoftProvider) AuthCodeURL

func (p *MicrosoftProvider) AuthCodeURL(state string) string

func (*MicrosoftProvider) ExchangeCode

func (p *MicrosoftProvider) ExchangeCode(ctx context.Context, code string) (*oauth2.Token, error)

func (*MicrosoftProvider) GetUserInfo

func (p *MicrosoftProvider) GetUserInfo(ctx context.Context, token *oauth2.Token) (OAuthUserInfo, error)

func (*MicrosoftProvider) Name

func (p *MicrosoftProvider) Name() string

type OAuthProvider

type OAuthProvider interface {
	Name() string
	AuthCodeURL(state string) string
	ExchangeCode(ctx context.Context, code string) (*oauth2.Token, error)
	GetUserInfo(ctx context.Context, token *oauth2.Token) (OAuthUserInfo, error)
}

type OAuthUserInfo

type OAuthUserInfo struct {
	ID    string
	Email string
	Name  string
}

type PasswordData

type PasswordData struct {
	Current string
	New     string
	Confirm string
}

PasswordData is validated by ProfileModule (password change sub-form).

type ProfileData

type ProfileData struct {
	Name  string
	Phone string
}

ProfileData is validated by ProfileModule (name/phone update).

type RegisterData

type RegisterData struct {
	Name     string
	Email    string
	Password string
	Phone    string
}

RegisterData is validated by RegisterModule.

type Rows

type Rows interface {
	Scan(dest ...any) error
	Next() bool
	Close() error
	Err() error
}

Rows interface abstracts scanning multiple rows.

type Scanner

type Scanner interface {
	Scan(dest ...any) error
}

Scanner interface abstracts scanning a row.

type Session

type Session struct {
	ID        string `json:"id"`
	UserID    string `json:"user_id"`
	ExpiresAt int64  `json:"expires_at"`
	IP        string `json:"ip,omitempty"`
	UserAgent string `json:"user_agent,omitempty"`
	CreatedAt int64  `json:"created_at"`
}

func CreateSession

func CreateSession(userID, ip, userAgent string) (Session, error)

func GetSession

func GetSession(id string) (Session, error)

type Store

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

type User

type User struct {
	ID        string `json:"id"`
	Email     string `json:"email,omitempty"`
	Name      string `json:"name"`
	Phone     string `json:"phone,omitempty"`
	Status    string `json:"status"` // "active", "suspended"
	CreatedAt int64  `json:"created_at"`
}

func CompleteOAuth

func CompleteOAuth(providerName string, r *http.Request, ip, ua string) (User, bool, error)

func CreateUser

func CreateUser(email, name, phone string) (User, error)

func GetUser

func GetUser(id string) (User, error)

func GetUserByEmail

func GetUserByEmail(email string) (User, error)

func Login

func Login(email, password string) (User, error)

func LoginLAN

func LoginLAN(rut string, r *http.Request) (User, error)