rbac-authorization-patterns_skill

Overview

This skill provides practical RBAC and multi-tenant authorization patterns for laneweaverTMS, focused on a Go + Echo backend with Supabase/Postgres. It documents role/permission models, DB schema, JWT claims, Echo middleware, and RLS policy examples tailored for freight brokerage workflows. Use it to speed up secure, tenant-isolated access controls and consistent authorization behavior.

How this skill works

It defines a resource:action permission model and seed system roles (admin, dispatcher, sales, finance, driver, readonly). The skill shows core DB tables (roles, permissions, role_permissions, user_roles, account_users) and index guidance for RLS performance. It provides JWT claim structure and Echo middleware for authentication, tenant context, role checks, and permission checks, plus sample middleware chaining. Finally it includes account-based and role-aware RLS policy patterns to enforce tenant isolation at the database level.

When to use it

• Designing user roles and permissions for freight brokerage operations
• Implementing Echo middleware for JWT auth, role, and permission checks
• Setting up account-based multi-tenant isolation and RLS policies
• Defining JWT claims to carry account, role, and optional permission data
• Choosing HTTP status codes and failure behaviors for auth flows

Best practices

• Keep permissions in resource:action format (e.g., loads:read, invoices:approve) to simplify checks
• Seed system roles and maintain role_permission mappings in DB; cache mappings or include permissions in JWT for performance
• Enforce TenantContext after authentication to fail fast on missing tenant info
• Layer middleware: Auth -> Tenant -> Role -> Permission to minimize unnecessary DB work
• Use RLS for row-level tenant isolation and combine with role checks for least privilege

Example use cases

• Protect /api/v1/loads endpoints: allow read to readonly/dispatcher/admin and limit writes to dispatcher/admin
• Issue JWTs with account_id and roles so handlers and RLS can enforce tenant scoping without extra queries
• Seed roles and permissions during deployment, then map users to roles per account in user_roles
• Create RLS policies on loads/customers/invoices so queries automatically filter to the caller’s accounts
• Implement RequirePermission middleware that checks JWT permissions first, then falls back to cached role-permission mapping