User Modules Reference

This skill provides usage instructions for all modules in github.com/weedbox/user-modules.

Module Index

Core

API

Optional

⚠️ Critical Rules

Source of Truth — Do NOT Fetch from GitHub

This file and its sub-files (modules/*.md) are the complete, authoritative reference for weedbox/user-modules. They contain all necessary implementation details including code examples, API endpoints, configuration, dependency injection patterns, and middleware usage. DO NOT browse github.com/weedbox/user-modules to look up source code — the answer is already here.

Dependency Injection: name Tags Required

All user-modules use Method 2 (weedbox generic). When injecting them in your Params, you MUST use name tags:

// ✅ Correct - name tags required for user-modules
type Params struct {
    weedbox.Params
    Database database.DatabaseConnector           // common-module: NO name tag
    User     *user.UserManager    `name:"user"`   // user-module: name tag required
    RBAC     *rbac.RBACManager    `name:"rbac"`   // user-module: name tag required
    Auth     *auth.AuthManager    `name:"auth"`   // user-module: name tag required
}

// ❌ Wrong - missing name tags
type Params struct {
    weedbox.Params
    User *user.UserManager
    Auth *auth.AuthManager
}

Module Loading Order

User-modules must be loaded in the correct order due to dependencies:

// ✅ Correct order
user.Module("user"),       // 1. User first (no user-module deps)
rbac.Module("rbac"),       // 2. RBAC second (no user-module deps)
auth.Module("auth"),       // 3. Auth third (depends on user + rbac)

// API modules (depend on auth)
user_apis.Module("user_apis"),
auth_apis.Module("auth_apis"),
role_apis.Module("role_apis"),
http_token_validator.Module("http_token_validator"),  // optional

Quick Start

Installation

go get github.com/weedbox/user-modules

Loading Modules

Add user-modules in the loadModules() phase of your modules.go:

import (
    "github.com/weedbox/user-modules/auth"
    "github.com/weedbox/user-modules/auth_apis"
    "github.com/weedbox/user-modules/http_token_validator"
    "github.com/weedbox/user-modules/rbac"
    "github.com/weedbox/user-modules/role_apis"
    "github.com/weedbox/user-modules/user"
    "github.com/weedbox/user-modules/user_apis"
)

func loadModules() ([]fx.Option, error) {
    modules := []fx.Option{
        // Infrastructure (from common-modules)
        http_server.Module("http_server"),
        sqlite_connector.Module("database"),

        // User modules
        user.Module("user"),
        rbac.Module("rbac"),
        auth.Module("auth"),

        // API modules
        http_token_validator.Module("http_token_validator"),
        user_apis.Module("user_apis"),
        auth_apis.Module("auth_apis"),
        role_apis.Module("role_apis"),
    }
    return modules, nil
}

This gives you:

• A default admin user (username: admin, password: 1qaz@WSX)
• Two builtin roles: admin, user
• JWT-based authentication with access/refresh token pairs
• REST API endpoints for user management, authentication, and role/resource management
• Global token validation on all HTTP routes

Configuration

[user]
bcrypt_cost = 12
min_password_length = 8
create_default_admin = true
default_admin_password = "your-secure-password"

[rbac]
init_default_roles = true

[auth]
jwt_secret = "your-production-secret-key"
access_token_expiry = "15m"
refresh_token_expiry = "168h"
issuer = "my-app"
mode = "standalone"          # or "gateway" behind a trusted ingress

Module Dependency Graph

database.DatabaseConnector (from common-modules)
    |
    +---> user.UserManager
    |         |
    +---> rbac.RBACManager
    |         |
    +---> auth.AuthManager <--- user.UserManager + rbac.RBACManager
              |
              +---> user_apis (+ http_server + user.UserManager)
              +---> auth_apis (+ http_server)
              +---> role_apis (+ http_server + rbac.RBACManager)
              +---> http_token_validator (+ http_server) [optional]

API Endpoints

Authentication (auth_apis)

User Management (user_apis)

Role Management (role_apis)

Extending Permissions

The builtin permissions cover user, auth, and role resources. To add your own, use the Option pattern on rbac.Module:

import (
    "github.com/weedbox/privy"
    "github.com/weedbox/user-modules/permissions"
    "github.com/weedbox/user-modules/rbac"
)

rbac.Module("rbac",
    rbac.WithResourceConfigs([]privy.ResourceConfig{
        {
            Key:         "product",
            Name:        "Product",
            Description: "Product management",
            Actions:     permissions.CRUDActions(), // full CRUD: create, read, update, delete, list
        },
        {
            Key:         "report",
            Name:        "Report",
            Description: "Report browsing",
            Actions: []privy.Action{  // custom subset using privy.DefineAction()
                privy.DefineAction("read", "Read", "Read report details"),
                privy.DefineAction("list", "List", "List reports"),
            },
        },
    }),
    rbac.WithDefaultRoles(map[string]privy.RoleConfig{
        "operator": {
            Name:        "Operator",
            Description: "Can manage products",
            Permissions: []string{"product.*"},
        },
    }),
)

Custom resources and roles are merged with the builtins. See permissions.md for details.

Authentication Flow

Client                    Server
  |                         |
  |-- POST /auth/login ---->|  (username + password)
  |<-- access + refresh ----|
  |                         |
  |-- GET /users ---------->|  (Authorization: Bearer <access_token>)
  |   [authenticate MW]     |  -> validates JWT, sets X-User-Info header
  |   [require_permission]  |  -> reads X-User-Info, checks RBAC
  |<-- 200 OK --------------|
  |                         |
  |-- POST /auth/refresh -->|  (refresh_token)
  |<-- new access+refresh --|  (old refresh token is revoked)
  |                         |
  |-- POST /auth/logout --->|  (refresh_token)
  |<-- 200 OK --------------|  (refresh token is revoked)

The two-layer middleware design (authenticate + require_permission) supports ingress/gateway architectures where token validation happens at the edge and user info is forwarded via the X-User-Info header.

Security — pick a trust mode. Because X-User-Info is a plain request header, whether authenticate trusts an inbound one is controlled by auth.mode: the default standalone strips it (identity comes only from a JWT this service validates), while gateway trusts a value injected by a trusted upstream. A directly-reachable service must not run in gateway mode, or a client can forge identity and roles. See auth: Security: Identity Trust Modes.

Using Auth Middleware in Custom Modules

When building custom API modules that need permission protection:

type Params struct {
    weedbox.Params
    HTTPServer *http_server.HTTPServer
    Auth       *auth.AuthManager `name:"auth"`
}

func (m *MyAPIs) OnStart(ctx context.Context) error {
    router := m.Params().HTTPServer.GetRouter().Group("/apis/v1")

    requirePerm := m.Params().Auth.GetMiddleware("require_permission").(func(string) gin.HandlerFunc)

    router.GET("/products", requirePerm("product.list"), m.listProducts)
    router.POST("/product", requirePerm("product.create"), m.createProduct)
    router.POST("/public", requirePerm("*"), m.publicHandler)  // "*" = no auth required

    return nil
}

func (m *MyAPIs) listProducts(c *gin.Context) {
    // Get authenticated user info from context
    session, ok := auth.GetSession(c)
    if ok {
        fmt.Printf("User: %s, Roles: %v\n", session.Username, session.Roles)
    }

    if auth.HasRole(c, "admin") {
        // admin-specific logic
    }
}

Context Helpers

Related Skills

• common-modules - Infrastructure modules (HTTP server, database, etc.)
• module-dev - Custom module development
• crud-api-dev - CRUD API patterns