Provide patterns for implementing Role-Based Access Control and multi-tenant authorization in laneweaverTMS. Use when implementing user roles, permissions, tenant isolation, Echo authorization middleware, RLS policies for multi-tenant access, or JWT claims structure for freight brokerage applications.
Provides RBAC patterns for Go/Echo apps with multi-tenant authorization. Use when implementing role-based middleware, JWT claims structures, or Supabase RLS policies for tenant isolation.
/plugin marketplace add linehaul-ai/linehaulai-claude-marketplace/plugin install laneweaver-tms-agents@linehaulai-claude-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Expert guidance for implementing Role-Based Access Control (RBAC) and multi-tenant authorization in a Go/Echo backend with Supabase/PostgreSQL.
Use when:
| Role | Description | Typical Access |
|---|---|---|
admin | Full system access | All resources, user management, system config |
dispatcher | Load management, carrier selection | Loads, carriers, tracking, dispatch operations |
sales | Account management, quotes | Customers, quotes, lanes, tenders |
finance | Invoicing, payments, reports | Invoices, carrier bills, payments, financial reports |
driver | Limited mobile access | Assigned loads only, status updates, document upload |
readonly | View-only access | Read all operational data, no modifications |
Permissions follow a resource:action pattern:
loads:read, loads:create, loads:update, loads:delete
carriers:read, carriers:create, carriers:update
customers:read, customers:create, customers:update
invoices:read, invoices:create, invoices:approve
reports:financial, reports:operational
users:manage
-- Roles table
CREATE TABLE public.roles (
id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
name TEXT NOT NULL UNIQUE,
description TEXT,
is_system_role BOOLEAN DEFAULT false,
created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
);
-- Permissions table
CREATE TABLE public.permissions (
id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
resource TEXT NOT NULL,
action TEXT NOT NULL,
description TEXT,
created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
UNIQUE(resource, action)
);
-- Role-Permission junction
CREATE TABLE public.role_permissions (
role_id UUID NOT NULL REFERENCES public.roles(id) ON DELETE CASCADE,
permission_id UUID NOT NULL REFERENCES public.permissions(id) ON DELETE CASCADE,
created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
PRIMARY KEY (role_id, permission_id)
);
-- User-Role junction (within account/tenant context)
CREATE TABLE public.user_roles (
user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
role_id UUID NOT NULL REFERENCES public.roles(id) ON DELETE CASCADE,
account_id UUID NOT NULL REFERENCES public.accounts(id) ON DELETE CASCADE,
created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
created_by UUID REFERENCES auth.users(id),
PRIMARY KEY (user_id, role_id, account_id)
);
-- Account-User junction for multi-tenant
CREATE TABLE public.account_users (
id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
account_id UUID NOT NULL REFERENCES public.accounts(id) ON DELETE CASCADE,
user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
is_primary BOOLEAN DEFAULT false,
invited_at TIMESTAMPTZ DEFAULT now() NOT NULL,
accepted_at TIMESTAMPTZ,
created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
UNIQUE(account_id, user_id)
);
-- Indexes for RLS policy performance
CREATE INDEX idx_user_roles_user_id ON public.user_roles(user_id);
CREATE INDEX idx_user_roles_account_id ON public.user_roles(account_id);
CREATE INDEX idx_account_users_user_id ON public.account_users(user_id);
CREATE INDEX idx_account_users_account_id ON public.account_users(account_id);
INSERT INTO public.roles (name, description, is_system_role) VALUES
('admin', 'Full system access', true),
('dispatcher', 'Load management and carrier selection', true),
('sales', 'Account management and quotes', true),
('finance', 'Invoicing, payments, and reports', true),
('driver', 'Limited mobile access for assigned loads', true),
('readonly', 'View-only access to operational data', true);
package middleware
type contextKey string
const (
ContextKeyUserID contextKey = "user_id"
ContextKeyAccountID contextKey = "account_id"
ContextKeyRoles contextKey = "roles"
ContextKeyUser contextKey = "user"
)
package auth
import "github.com/golang-jwt/jwt/v5"
type Claims struct {
jwt.RegisteredClaims
UserID string `json:"user_id"`
Email string `json:"email"`
AccountID string `json:"account_id"`
Roles []string `json:"roles"`
Permissions []string `json:"permissions,omitempty"` // Optional: can derive from roles
}
Validates JWT and extracts claims into context:
package middleware
import (
"net/http"
"strings"
"github.com/labstack/echo/v4"
)
func JWTAuth(jwtSecret []byte) echo.MiddlewareFunc {
return func(next echo.HandlerFunc) echo.HandlerFunc {
return func(c echo.Context) error {
authHeader := c.Request().Header.Get("Authorization")
if authHeader == "" {
return echo.NewHTTPError(http.StatusUnauthorized, "missing authorization header")
}
tokenString := strings.TrimPrefix(authHeader, "Bearer ")
if tokenString == authHeader {
return echo.NewHTTPError(http.StatusUnauthorized, "invalid authorization format")
}
claims, err := ValidateToken(tokenString, jwtSecret)
if err != nil {
return echo.NewHTTPError(http.StatusUnauthorized, "invalid or expired token")
}
// Store in context for downstream handlers
c.Set(string(ContextKeyUserID), claims.UserID)
c.Set(string(ContextKeyAccountID), claims.AccountID)
c.Set(string(ContextKeyRoles), claims.Roles)
c.Set(string(ContextKeyUser), claims)
return next(c)
}
}
}
Ensures valid tenant context after authentication:
func TenantContext() echo.MiddlewareFunc {
return func(next echo.HandlerFunc) echo.HandlerFunc {
return func(c echo.Context) error {
accountID := c.Get(string(ContextKeyAccountID))
if accountID == nil || accountID.(string) == "" {
return echo.NewHTTPError(http.StatusForbidden, "no tenant context")
}
// Optionally validate account exists and is active
// This can be cached for performance
return next(c)
}
}
}
// RequireRole checks if user has any of the specified roles
func RequireRole(roles ...string) echo.MiddlewareFunc {
return func(next echo.HandlerFunc) echo.HandlerFunc {
return func(c echo.Context) error {
userRoles, ok := c.Get(string(ContextKeyRoles)).([]string)
if !ok || len(userRoles) == 0 {
return echo.NewHTTPError(http.StatusForbidden, "no roles assigned")
}
for _, required := range roles {
for _, userRole := range userRoles {
if userRole == required {
return next(c)
}
}
}
return echo.NewHTTPError(http.StatusForbidden, "insufficient role permissions")
}
}
}
// RequireAnyRole is an alias for RequireRole (OR logic)
var RequireAnyRole = RequireRole
// RequireAllRoles checks if user has ALL specified roles
func RequireAllRoles(roles ...string) echo.MiddlewareFunc {
return func(next echo.HandlerFunc) echo.HandlerFunc {
return func(c echo.Context) error {
userRoles, ok := c.Get(string(ContextKeyRoles)).([]string)
if !ok {
return echo.NewHTTPError(http.StatusForbidden, "no roles assigned")
}
userRoleSet := make(map[string]bool)
for _, r := range userRoles {
userRoleSet[r] = true
}
for _, required := range roles {
if !userRoleSet[required] {
return echo.NewHTTPError(http.StatusForbidden, "missing required role")
}
}
return next(c)
}
}
}
// RequirePermission checks for specific resource:action permission
func RequirePermission(resource, action string) echo.MiddlewareFunc {
return func(next echo.HandlerFunc) echo.HandlerFunc {
return func(c echo.Context) error {
claims, ok := c.Get(string(ContextKeyUser)).(*Claims)
if !ok {
return echo.NewHTTPError(http.StatusForbidden, "invalid user context")
}
// Check explicit permissions if available
requiredPerm := resource + ":" + action
for _, perm := range claims.Permissions {
if perm == requiredPerm || perm == resource+":*" || perm == "*:*" {
return next(c)
}
}
// Fallback: derive from roles (requires DB lookup or cached mapping)
if hasPermissionViaRole(claims.Roles, resource, action) {
return next(c)
}
return echo.NewHTTPError(http.StatusForbidden, "permission denied")
}
}
}
// hasPermissionViaRole checks role-permission mapping
// In production, use cached lookup or include permissions in JWT
func hasPermissionViaRole(roles []string, resource, action string) bool {
// Admin role has all permissions
for _, role := range roles {
if role == "admin" {
return true
}
}
// Role-permission mapping (simplified; use DB in production)
rolePerms := map[string][]string{
"dispatcher": {"loads:*", "carriers:read", "tracking:*"},
"sales": {"customers:*", "quotes:*", "lanes:*", "tenders:*"},
"finance": {"invoices:*", "payments:*", "reports:financial"},
"driver": {"loads:read", "loads:update_status", "documents:upload"},
"readonly": {"loads:read", "carriers:read", "customers:read"},
}
requiredPerm := resource + ":" + action
for _, role := range roles {
for _, perm := range rolePerms[role] {
if matchPermission(perm, requiredPerm) {
return true
}
}
}
return false
}
func matchPermission(pattern, required string) bool {
if pattern == required {
return true
}
// Handle wildcard: "loads:*" matches "loads:read"
if strings.HasSuffix(pattern, ":*") {
prefix := strings.TrimSuffix(pattern, "*")
return strings.HasPrefix(required, prefix)
}
return false
}
Apply middleware in order: Auth -> Tenant -> Role -> Permission:
func SetupRoutes(e *echo.Echo, cfg *config.Config) {
// Public routes (no auth required)
e.GET("/health", handlers.HealthCheck)
// API routes with auth
api := e.Group("/api/v1")
api.Use(middleware.JWTAuth(cfg.JWTSecret))
api.Use(middleware.TenantContext())
// Load routes - dispatchers and admins
loads := api.Group("/loads")
loads.Use(middleware.RequireRole("admin", "dispatcher", "sales", "readonly"))
loads.GET("", handlers.ListLoads)
loads.GET("/:id", handlers.GetLoad)
// Modify operations require specific roles
loads.POST("", handlers.CreateLoad, middleware.RequireRole("admin", "dispatcher", "sales"))
loads.PUT("/:id", handlers.UpdateLoad, middleware.RequireRole("admin", "dispatcher"))
// Finance routes
finance := api.Group("/finance")
finance.Use(middleware.RequireRole("admin", "finance"))
finance.GET("/invoices", handlers.ListInvoices)
finance.POST("/invoices", handlers.CreateInvoice)
// Admin-only routes
admin := api.Group("/admin")
admin.Use(middleware.RequireRole("admin"))
admin.GET("/users", handlers.ListUsers)
admin.POST("/users", handlers.CreateUser)
}
ALTER TABLE public.loads ENABLE ROW LEVEL SECURITY;
ALTER TABLE public.customers ENABLE ROW LEVEL SECURITY;
ALTER TABLE public.carriers ENABLE ROW LEVEL SECURITY;
ALTER TABLE public.invoices ENABLE ROW LEVEL SECURITY;
-- Users see only their account's loads
CREATE POLICY "Users see only their account loads"
ON public.loads
FOR SELECT
TO authenticated
USING (
account_id IN (
SELECT account_id
FROM public.account_users
WHERE user_id = (SELECT auth.uid())
)
);
-- Users can create loads for their account
CREATE POLICY "Users create loads for their account"
ON public.loads
FOR INSERT
TO authenticated
WITH CHECK (
account_id IN (
SELECT account_id
FROM public.account_users
WHERE user_id = (SELECT auth.uid())
)
);
-- Users can update their account's loads
CREATE POLICY "Users update their account loads"
ON public.loads
FOR UPDATE
TO authenticated
USING (
account_id IN (
SELECT account_id
FROM public.account_users
WHERE user_id = (SELECT auth.uid())
)
)
WITH CHECK (
account_id IN (
SELECT account_id
FROM public.account_users
WHERE user_id = (SELECT auth.uid())
)
);
Combine tenant isolation with role restrictions:
-- Helper function to check user roles within account
CREATE OR REPLACE FUNCTION public.user_has_role(required_roles TEXT[])
RETURNS BOOLEAN
LANGUAGE sql
SECURITY DEFINER
STABLE
AS $$
SELECT EXISTS (
SELECT 1
FROM public.user_roles ur
JOIN public.roles r ON ur.role_id = r.id
WHERE ur.user_id = (SELECT auth.uid())
AND r.name = ANY(required_roles)
);
$$;
-- Only finance and admin can view invoices
CREATE POLICY "Finance users view invoices"
ON public.customer_invoices
FOR SELECT
TO authenticated
USING (
account_id IN (
SELECT account_id
FROM public.account_users
WHERE user_id = (SELECT auth.uid())
)
AND public.user_has_role(ARRAY['admin', 'finance', 'readonly'])
);
-- Only finance and admin can create invoices
CREATE POLICY "Finance users create invoices"
ON public.customer_invoices
FOR INSERT
TO authenticated
WITH CHECK (
account_id IN (
SELECT account_id
FROM public.account_users
WHERE user_id = (SELECT auth.uid())
)
AND public.user_has_role(ARRAY['admin', 'finance'])
);
Drivers see only their assigned loads:
-- Drivers see only loads assigned to them
CREATE POLICY "Drivers see assigned loads"
ON public.loads
FOR SELECT
TO authenticated
USING (
-- Driver is assigned to this load
driver_user_id = (SELECT auth.uid())
OR
-- Or user has broader access via role
(
account_id IN (
SELECT account_id
FROM public.account_users
WHERE user_id = (SELECT auth.uid())
)
AND public.user_has_role(ARRAY['admin', 'dispatcher', 'sales', 'readonly'])
)
);
| Scenario | Status Code | When to Use |
|---|---|---|
| Missing or invalid token | 401 Unauthorized | Token absent, expired, or malformed |
| Valid token, insufficient permissions | 403 Forbidden | User authenticated but lacks required role/permission |
| Resource not found (or hidden) | 404 Not Found | Resource doesn't exist OR hiding existence is security concern |
Use 404 instead of 403 when revealing resource existence is a security concern:
func GetLoad(c echo.Context) error {
loadID := c.Param("id")
accountID := c.Get(string(middleware.ContextKeyAccountID)).(string)
load, err := repo.GetLoad(c.Request().Context(), loadID)
if err != nil {
if errors.Is(err, sql.ErrNoRows) {
// Resource doesn't exist
return echo.NewHTTPError(http.StatusNotFound, "load not found")
}
return echo.NewHTTPError(http.StatusInternalServerError, "failed to fetch load")
}
// Check tenant ownership - return 404 to hide existence
if load.AccountID != accountID {
return echo.NewHTTPError(http.StatusNotFound, "load not found")
}
return c.JSON(http.StatusOK, load)
}
type ErrorResponse struct {
Error string `json:"error"`
Code string `json:"code,omitempty"`
Details string `json:"details,omitempty"`
}
// Authorization error examples
// 401: {"error": "missing authorization header", "code": "AUTH_REQUIRED"}
// 401: {"error": "invalid or expired token", "code": "TOKEN_INVALID"}
// 403: {"error": "insufficient role permissions", "code": "ROLE_REQUIRED"}
// 403: {"error": "permission denied", "code": "PERMISSION_DENIED"}
Include only essential claims; derive others from database:
type MinimalClaims struct {
jwt.RegisteredClaims
UserID string `json:"sub"` // Use standard 'sub' claim
AccountID string `json:"account_id"`
Roles []string `json:"roles"` // Include for middleware checks
}
For reduced database lookups, include permissions:
type FullClaims struct {
jwt.RegisteredClaims
UserID string `json:"sub"`
Email string `json:"email"`
AccountID string `json:"account_id"`
AccountName string `json:"account_name"`
Roles []string `json:"roles"`
Permissions []string `json:"permissions"` // Flattened from roles
}
func GenerateToken(user *User, account *Account, roles []string, permissions []string) (string, error) {
now := time.Now()
claims := &FullClaims{
RegisteredClaims: jwt.RegisteredClaims{
Subject: user.ID,
IssuedAt: jwt.NewNumericDate(now),
ExpiresAt: jwt.NewNumericDate(now.Add(24 * time.Hour)),
Issuer: "laneweavertms",
},
UserID: user.ID,
Email: user.Email,
AccountID: account.ID,
AccountName: account.Name,
Roles: roles,
Permissions: permissions,
}
token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
return token.SignedString(jwtSecret)
}
RBAC Schema:
[ ] roles, permissions, role_permissions tables created
[ ] user_roles table includes account_id for multi-tenant
[ ] account_users table for tenant membership
[ ] Indexes on user_id, account_id columns for RLS performance
Middleware Chain:
[ ] JWT validation middleware extracts claims to context
[ ] Tenant context middleware validates account_id
[ ] Role middleware checks user roles array
[ ] Permission middleware checks specific resource:action
RLS Policies:
[ ] RLS enabled on all tenant-owned tables
[ ] SELECT policies use account_id IN (SELECT from account_users)
[ ] INSERT policies use WITH CHECK for account_id
[ ] UPDATE policies use both USING and WITH CHECK
[ ] auth.uid() wrapped in SELECT for query plan caching
[ ] Indexes exist on columns used in RLS conditions
JWT Claims:
[ ] Token includes user_id, account_id, roles
[ ] Token expiration set appropriately (e.g., 24 hours)
[ ] Refresh token mechanism for long-lived sessions
Error Handling:
[ ] 401 for missing/invalid authentication
[ ] 403 for valid auth but insufficient permissions
[ ] 404 when hiding resource existence is security concern
[ ] Error responses don't leak sensitive information
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.