rbac

README

rbac

A weedbox module that provides role-based access control (RBAC) powered by privy. Supports extensible resource and role definitions via the Option pattern.

Overview

The RBAC module manages permission resources and roles using database-backed storage (via GORM). On startup, it:

1. Initializes the privy GORM storage (creates tables if needed)
2. Registers builtin resources (user, auth) plus any user-provided extra resources
3. Creates builtin roles (admin, user) plus any user-provided extra roles (if enabled)

Dependencies

Dependency	Source	Description
database.DatabaseConnector	common-modules	GORM database connection

Module Registration

Basic Usage

rbac.Module("rbac")

With Custom Resources and Roles

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(),
        },
    }),
    rbac.WithDefaultRoles(map[string]privy.RoleConfig{
        "operator": {
            Name:        "Operator",
            Description: "Product operator",
            Permissions: []string{"product.*"},
        },
    }),
)

Custom resources and roles are merged with the builtins. If a custom role key matches a builtin key (e.g., "admin"), the custom definition takes precedence.

Configuration

Key	Type	Default	Description
init_default_roles	bool	true	Whether to create default roles on startup

Options

Option	Description
WithResourceConfigs(configs []privy.ResourceConfig)	Extra resource definitions to merge with builtins
WithDefaultRoles(roles map[string]privy.RoleConfig)	Extra role definitions to merge with builtins

API Reference

RBACManager Methods

Permission Checking:

Method	Signature	Description
CheckPermission	(roleKey, permission string) (bool, error)	Check if a single role has a permission
CheckPermissions	(roleKeys []string, permission string) (bool, error)	Check if any role in a list has a permission

Role Management:

Method	Signature	Description
CreateRole	(key string, config privy.RoleConfig) (*privy.Role, error)	Create a new role
GetRole	(key string) (*privy.Role, error)	Get a role by key
ListRoles	() ([]privy.Role, error)	List all roles
DeleteRole	(key string) error	Delete a role
AssignPermissions	(roleKey string, permissions []string) error	Add permissions to a role
RemovePermissions	(roleKey string, permissions []string) error	Remove permissions from a role

Resource Management:

Method	Signature	Description
GetResource	(path string) (*privy.Resource, error)	Get a resource by path
ListResources	() ([]privy.Resource, error)	List all top-level resources
GetManager	() *privy.Manager	Get the underlying privy manager

Example: Runtime Permission Check

// In your handler or service
allowed, err := rbacManager.CheckPermissions(userRoles, "product.create")
if err != nil {
    // handle error
}
if !allowed {
    // return 403
}

Documentation

Index

• Constants
• func Module(scope string, opts ...Option) fx.Option
• type Option
  • func WithDefaultRoles(roles map[string]privy.RoleConfig) Option
  • func WithResourceConfigs(configs []privy.ResourceConfig) Option
• type Params
• type RBACManager
  • func (m *RBACManager) AssignPermissions(roleKey string, permissions []string) error
  • func (m *RBACManager) CheckPermission(roleKey, permission string) (bool, error)
  • func (m *RBACManager) CheckPermissions(roleKeys []string, permission string) (bool, error)
  • func (m *RBACManager) CreateRole(key string, config privy.RoleConfig) (*privy.Role, error)
  • func (m *RBACManager) DeleteRole(key string) error
  • func (m *RBACManager) GetManager() *privy.Manager
  • func (m *RBACManager) GetResource(path string) (*privy.Resource, error)
  • func (m *RBACManager) GetRole(key string) (*privy.Role, error)
  • func (m *RBACManager) InitDefaultConfigs()
  • func (m *RBACManager) ListResources() ([]privy.Resource, error)
  • func (m *RBACManager) ListRoles() ([]privy.Role, error)
  • func (m *RBACManager) OnStart(ctx context.Context) error
  • func (m *RBACManager) OnStop(ctx context.Context) error
  • func (m *RBACManager) RemovePermissions(roleKey string, permissions []string) error
  • func (m *RBACManager) UpdateRole(key string, config privy.RoleConfig) (*privy.Role, error)

Constants

const ModuleName = "RBAC"

Functions

func Module

func Module(scope string, opts ...Option) fx.Option

Types

type Option

type Option func(*options)

Option is a function that configures the RBAC module

func WithDefaultRoles

func WithDefaultRoles(roles map[string]privy.RoleConfig) Option

WithDefaultRoles sets extra default roles to merge with builtins

func WithResourceConfigs

func WithResourceConfigs(configs []privy.ResourceConfig) Option

WithResourceConfigs sets extra resource configurations to merge with builtins

type Params

type Params struct {
	weedbox.Params
	Database database.DatabaseConnector
}

type RBACManager

type RBACManager struct {
	weedbox.Module[*Params]
	// contains filtered or unexported fields
}

func (*RBACManager) AssignPermissions

func (m *RBACManager) AssignPermissions(roleKey string, permissions []string) error

AssignPermissions adds permissions to a role

func (*RBACManager) CheckPermission

func (m *RBACManager) CheckPermission(roleKey, permission string) (bool, error)

CheckPermission checks if a role has the required permission

func (*RBACManager) CheckPermissions

func (m *RBACManager) CheckPermissions(roleKeys []string, permission string) (bool, error)

CheckPermissions checks if any of the given roles has the required permission

func (*RBACManager) CreateRole

func (m *RBACManager) CreateRole(key string, config privy.RoleConfig) (*privy.Role, error)

CreateRole creates a new role

func (*RBACManager) DeleteRole

func (m *RBACManager) DeleteRole(key string) error

DeleteRole deletes a role

func (*RBACManager) GetManager

func (m *RBACManager) GetManager() *privy.Manager

GetManager returns the privy manager

func (*RBACManager) GetResource

func (m *RBACManager) GetResource(path string) (*privy.Resource, error)

GetResource gets a resource by path

func (*RBACManager) GetRole

func (m *RBACManager) GetRole(key string) (*privy.Role, error)

GetRole gets a role by key

func (*RBACManager) InitDefaultConfigs

func (m *RBACManager) InitDefaultConfigs()

func (*RBACManager) ListResources

func (m *RBACManager) ListResources() ([]privy.Resource, error)

ListResources lists all top-level resources

func (*RBACManager) ListRoles

func (m *RBACManager) ListRoles() ([]privy.Role, error)

ListRoles lists all roles

func (*RBACManager) OnStart

func (m *RBACManager) OnStart(ctx context.Context) error

func (*RBACManager) OnStop

func (m *RBACManager) OnStop(ctx context.Context) error

func (*RBACManager) RemovePermissions

func (m *RBACManager) RemovePermissions(roleKey string, permissions []string) error

RemovePermissions removes permissions from a role

func (*RBACManager) UpdateRole

func (m *RBACManager) UpdateRole(key string, config privy.RoleConfig) (*privy.Role, error)

UpdateRole updates an existing role's name, description, and permissions