feat: implement multi-guard support across API methods, middleware, and database schema

Author: MichaelAndish

README.md

@@ -40,8 +40,14 @@ The package utilizes 5 tables:
 1. `permissions`: Stores permission names (e.g., `users.list`, `articles.create`).
 2. `roles`: Stores role names (e.g., `admin`, `editor`).
 3. `role_has_permissions`: Links permissions to roles (which roles can perform which actions).
-4. `model_has_roles`: Assigns roles to models (e.g., assigning the `editor` role to a specific user within a specific workspace/team).
-5. `model_has_permissions`: Assigns direct permission overrides to models (e.g., giving a specific user `articles.delete` even if their role doesn't allow it).
+4. `model_has_roles`: Assigns roles to models (e.g., assigning the `editor` role to a specific user within a specific workspace/team using `team_id`).
+5. `model_has_permissions`: Assigns direct permission overrides to models (e.g., giving a specific user `articles.delete` even if their role doesn't allow it, also scoped by `team_id`).
+
+### The `team_id` Architecture
+Both `model_has_roles` and `model_has_permissions` contain an optional `team_id UUID` column. This is the foundation for multi-tenant and workspace-scoped authorization. 
+- If a user is assigned a role with `team_id = NULL`, it is a **global** role.
+- If assigned with a specific `team_id`, the user only possesses that role/permission when operating within the context of that specific team.
+The `team_id` column is built into the Primary Key of these tables to allow a user to hold different roles across different teams.
 
 ### Understanding `guard_name`
 

gate.go

@@ -62,12 +62,20 @@ func NewGate(db DBTX, cfg *Config) *Gate {
 	}
 }
 
+// resolveGuardName returns the default guard name if the provided one is empty.
+func (g *Gate) resolveGuardName(guardName string) string {
+	if guardName == "" {
+		return g.cfg.DefaultGuardName
+	}
+	return guardName
+}
+
 // LoadPolicy fetches all role-permission associations from the database
 // and caches them in memory. This is thread-safe and should be run on boot
 // or when permissions are updated.
 func (g *Gate) LoadPolicy(ctx context.Context) error {
 	query := fmt.Sprintf(`
-		SELECT r.name, p.name
+		SELECT r.guard_name, r.name, p.name
 		FROM %s rhp
 		JOIN %s r ON r.id = rhp.role_id
 		JOIN %s p ON p.id = rhp.permission_id
@@ -83,15 +91,16 @@ func (g *Gate) LoadPolicy(ctx context.Context) error {
 	newCache := make(map[string]map[string]bool)
 
 	for rows.Next() {
-		var roleName, permissionName string
-		if err := rows.Scan(&roleName, &permissionName); err != nil {
+		var guardName, roleName, permissionName string
+		if err := rows.Scan(&guardName, &roleName, &permissionName); err != nil {
 			return fmt.Errorf("wpd-gogate: scan role permission row: %w", err)
 		}
 
-		if _, exists := newCache[roleName]; !exists {
-			newCache[roleName] = make(map[string]bool)
+		cacheKey := guardName + ":" + roleName
+		if _, exists := newCache[cacheKey]; !exists {
+			newCache[cacheKey] = make(map[string]bool)
 		}
-		newCache[roleName][permissionName] = true
+		newCache[cacheKey][permissionName] = true
 	}
 
 	if err := rows.Err(); err != nil {
@@ -108,11 +117,14 @@ func (g *Gate) LoadPolicy(ctx context.Context) error {
 
 // HasRolePermission performs an in-memory O(1) check of whether a role
 // is assigned a specific permission.
-func (g *Gate) HasRolePermission(roleName, permissionName string) bool {
+func (g *Gate) HasRolePermission(guardName, roleName, permissionName string) bool {
+	guardName = g.resolveGuardName(guardName)
+
 	g.mu.RLock()
 	defer g.mu.RUnlock()
 
-	permissions, exists := g.rolePermissions[roleName]
+	cacheKey := guardName + ":" + roleName
+	permissions, exists := g.rolePermissions[cacheKey]
 	if !exists {
 		return false
 	}
@@ -123,25 +135,55 @@ func (g *Gate) HasRolePermission(roleName, permissionName string) bool {
 // It queries both direct permissions and roles in a single database round-trip (UNION ALL),
 // then maps them against the in-memory cache to determine access.
 // teamID is optional and can be nil to check global assignments.
-func (g *Gate) Check(ctx context.Context, modelType string, modelID any, permissionName string, teamID any) (bool, error) {
-	query := fmt.Sprintf(`
-		SELECT 'role' AS type, r.name AS value
-		FROM %s mhr
-		JOIN %s r ON r.id = mhr.role_id
-		WHERE mhr.model_type = $1
-		  AND mhr.model_id = $2
-		  AND mhr.team_id IS NOT DISTINCT FROM $3
-		UNION ALL
-		SELECT 'permission' AS type, p.name AS value
-		FROM %s mhp
-		JOIN %s p ON p.id = mhp.permission_id
-		WHERE mhp.model_type = $1
-		  AND mhp.model_id = $2
-		  AND mhp.team_id IS NOT DISTINCT FROM $3
-		  AND p.name = $4
-	`, g.cfg.ModelHasRolesTable, g.cfg.RolesTable, g.cfg.ModelHasPermissionsTable, g.cfg.PermissionsTable)
-
-	rows, err := g.db.QueryContext(ctx, query, modelType, modelID, teamID, permissionName)
+func (g *Gate) Check(ctx context.Context, modelType string, modelID any, permissionName string, guardName string, teamID any) (bool, error) {
+	guardName = g.resolveGuardName(guardName)
+	
+	var query string
+	var args []any
+
+	if IsNilOrEmpty(teamID) {
+		query = fmt.Sprintf(`
+			SELECT 'role' AS type, r.name AS value
+			FROM %s mhr
+			JOIN %s r ON r.id = mhr.role_id
+			WHERE mhr.model_type = $1
+			  AND mhr.model_id = $2
+			  AND mhr.team_id IS NULL
+			  AND r.guard_name = $3
+			UNION ALL
+			SELECT 'permission' AS type, p.name AS value
+			FROM %s mhp
+			JOIN %s p ON p.id = mhp.permission_id
+			WHERE mhp.model_type = $1
+			  AND mhp.model_id = $2
+			  AND mhp.team_id IS NULL
+			  AND p.name = $4
+			  AND p.guard_name = $3
+		`, g.cfg.ModelHasRolesTable, g.cfg.RolesTable, g.cfg.ModelHasPermissionsTable, g.cfg.PermissionsTable)
+		args = []any{modelType, modelID, guardName, permissionName}
+	} else {
+		query = fmt.Sprintf(`
+			SELECT 'role' AS type, r.name AS value
+			FROM %s mhr
+			JOIN %s r ON r.id = mhr.role_id
+			WHERE mhr.model_type = $1
+			  AND mhr.model_id = $2
+			  AND mhr.team_id = $5
+			  AND r.guard_name = $3
+			UNION ALL
+			SELECT 'permission' AS type, p.name AS value
+			FROM %s mhp
+			JOIN %s p ON p.id = mhp.permission_id
+			WHERE mhp.model_type = $1
+			  AND mhp.model_id = $2
+			  AND mhp.team_id = $5
+			  AND p.name = $4
+			  AND p.guard_name = $3
+		`, g.cfg.ModelHasRolesTable, g.cfg.RolesTable, g.cfg.ModelHasPermissionsTable, g.cfg.PermissionsTable)
+		args = []any{modelType, modelID, guardName, permissionName, teamID}
+	}
+
+	rows, err := g.db.QueryContext(ctx, query, args...)
 	if err != nil {
 		return false, fmt.Errorf("wpd-gogate: query access records: %w", err)
 	}
@@ -160,7 +202,7 @@ func (g *Gate) Check(ctx context.Context, modelType string, modelID any, permiss
 
 		if recordType == "role" {
 			// Check the in-memory cache for this role
-			if g.HasRolePermission(value, permissionName) {
+			if g.HasRolePermission(guardName, value, permissionName) {
 				return true, nil
 			}
 		}

gate_integration_test.go

@@ -119,7 +119,7 @@ func TestIntegration_Postgres(t *testing.T) {
 	}
 
 	// Associate permissions with roles
-	editorRole := gate.Role("editor")
+	editorRole := gate.Role("editor", "web")
 	err = editorRole.GivePermissionTo(ctx, "publish:articles")
 	if err != nil {
 		t.Fatalf("failed to assign publish:articles to editor: %v", err)
@@ -129,29 +129,29 @@ func TestIntegration_Postgres(t *testing.T) {
 		t.Fatalf("failed to assign read:articles to editor: %v", err)
 	}
 
-	viewerRole := gate.Role("viewer")
+	viewerRole := gate.Role("viewer", "web")
 	err = viewerRole.GivePermissionTo(ctx, "read:articles")
 	if err != nil {
 		t.Fatalf("failed to assign read:articles to viewer: %v", err)
 	}
 
-	writerRole := gate.Role("writer")
+	writerRole := gate.Role("writer", "web")
 	err = writerRole.GivePermissionTo(ctx, "create:articles")
 	if err != nil {
 		t.Fatalf("failed to assign create:articles to writer: %v", err)
 	}
 
 	// Verify local cache updates
-	if !gate.HasRolePermission("editor", "publish:articles") {
+	if !gate.HasRolePermission("web", "editor", "publish:articles") {
 		t.Error("expected editor to have publish:articles in cache")
 	}
-	if !gate.HasRolePermission("editor", "read:articles") {
+	if !gate.HasRolePermission("web", "editor", "read:articles") {
 		t.Error("expected editor to have read:articles in cache")
 	}
-	if !gate.HasRolePermission("writer", "create:articles") {
+	if !gate.HasRolePermission("web", "writer", "create:articles") {
 		t.Error("expected writer to have create:articles in cache")
 	}
-	if gate.HasRolePermission("viewer", "publish:articles") {
+	if gate.HasRolePermission("web", "viewer", "publish:articles") {
 		t.Error("viewer should not have publish:articles in cache")
 	}
 
@@ -163,7 +163,7 @@ func TestIntegration_Postgres(t *testing.T) {
 	userInTeam := gate.Model("users", userID, teamID)
 
 	// Check initially has no access
-	ok, err := userInTeam.Can(ctx, "read:articles")
+	ok, err := userInTeam.Can(ctx, "read:articles", "web")
 	if err != nil {
 		t.Fatalf("Can failed: %v", err)
 	}
@@ -172,13 +172,13 @@ func TestIntegration_Postgres(t *testing.T) {
 	}
 
 	// Assign viewer role in teamID
-	err = userInTeam.AssignRole(ctx, "viewer")
+	err = userInTeam.AssignRole(ctx, "viewer", "web")
 	if err != nil {
 		t.Fatalf("failed to assign viewer role: %v", err)
 	}
 
 	// Verify access allowed
-	ok, err = userInTeam.Can(ctx, "read:articles")
+	ok, err = userInTeam.Can(ctx, "read:articles", "web")
 	if err != nil {
 		t.Fatalf("Can failed: %v", err)
 	}
@@ -188,7 +188,7 @@ func TestIntegration_Postgres(t *testing.T) {
 
 	// Verify check is scoped to teamID (checking otherTeamID should return false)
 	userInOtherTeam := gate.Model("users", userID, otherTeamID)
-	ok, err = userInOtherTeam.Can(ctx, "read:articles")
+	ok, err = userInOtherTeam.Can(ctx, "read:articles", "web")
 	if err != nil {
 		t.Fatalf("Can failed: %v", err)
 	}
@@ -198,18 +198,18 @@ func TestIntegration_Postgres(t *testing.T) {
 
 	// Test case: Fully isolated multi-workspace roles (writer in Team A, viewer in Team B)
 	userTeamA := gate.Model("users", userID, teamID)
-	err = userTeamA.AssignRole(ctx, "writer")
+	err = userTeamA.AssignRole(ctx, "writer", "web")
 	if err != nil {
 		t.Fatalf("failed to assign writer role in Team A: %v", err)
 	}
 	userTeamB := gate.Model("users", userID, otherTeamID)
-	err = userTeamB.AssignRole(ctx, "viewer")
+	err = userTeamB.AssignRole(ctx, "viewer", "web")
 	if err != nil {
 		t.Fatalf("failed to assign viewer role in Team B: %v", err)
 	}
 
 	// In Team A (writer role assigned), user has create:articles
-	ok, err = userTeamA.Can(ctx, "create:articles")
+	ok, err = userTeamA.Can(ctx, "create:articles", "web")
 	if err != nil {
 		t.Fatalf("Can failed: %v", err)
 	}
@@ -218,14 +218,14 @@ func TestIntegration_Postgres(t *testing.T) {
 	}
 
 	// In Team B (viewer role assigned), user has read:articles but NOT create:articles
-	ok, err = userTeamB.Can(ctx, "read:articles")
+	ok, err = userTeamB.Can(ctx, "read:articles", "web")
 	if err != nil {
 		t.Fatalf("Can failed: %v", err)
 	}
 	if !ok {
 		t.Error("expected user to have read:articles access in Team B (viewer)")
 	}
-	ok, err = userTeamB.Can(ctx, "create:articles")
+	ok, err = userTeamB.Can(ctx, "create:articles", "web")
 	if err != nil {
 		t.Fatalf("Can failed: %v", err)
 	}
@@ -234,23 +234,23 @@ func TestIntegration_Postgres(t *testing.T) {
 	}
 
 	// Clean up Team A's writer role and Team B's viewer role
-	err = userTeamA.RemoveRole(ctx, "writer")
+	err = userTeamA.RemoveRole(ctx, "writer", "web")
 	if err != nil {
 		t.Fatalf("failed to remove writer role from Team A: %v", err)
 	}
-	err = userTeamB.RemoveRole(ctx, "viewer")
+	err = userTeamB.RemoveRole(ctx, "viewer", "web")
 	if err != nil {
 		t.Fatalf("failed to remove viewer role from Team B: %v", err)
 	}
 
 	// Give direct permission override in teamID
-	err = userInTeam.GivePermissionTo(ctx, "admin:settings")
+	err = userInTeam.GivePermissionTo(ctx, "admin:settings", "web")
 	if err != nil {
 		t.Fatalf("failed to give direct permission: %v", err)
 	}
 
 	// Verify direct permission works
-	ok, err = userInTeam.Can(ctx, "admin:settings")
+	ok, err = userInTeam.Can(ctx, "admin:settings", "web")
 	if err != nil {
 		t.Fatalf("Can failed: %v", err)
 	}
@@ -259,7 +259,7 @@ func TestIntegration_Postgres(t *testing.T) {
 	}
 
 	// Verify other team has no direct permission
-	ok, err = userInOtherTeam.Can(ctx, "admin:settings")
+	ok, err = userInOtherTeam.Can(ctx, "admin:settings", "web")
 	if err != nil {
 		t.Fatalf("Can failed: %v", err)
 	}
@@ -268,13 +268,13 @@ func TestIntegration_Postgres(t *testing.T) {
 	}
 
 	// Revoke direct permission
-	err = userInTeam.RevokePermissionTo(ctx, "admin:settings")
+	err = userInTeam.RevokePermissionTo(ctx, "admin:settings", "web")
 	if err != nil {
 		t.Fatalf("failed to revoke direct permission: %v", err)
 	}
 
 	// Verify direct permission revoked
-	ok, err = userInTeam.Can(ctx, "admin:settings")
+	ok, err = userInTeam.Can(ctx, "admin:settings", "web")
 	if err != nil {
 		t.Fatalf("Can failed: %v", err)
 	}
@@ -283,13 +283,13 @@ func TestIntegration_Postgres(t *testing.T) {
 	}
 
 	// Revoke role viewer
-	err = userInTeam.RemoveRole(ctx, "viewer")
+	err = userInTeam.RemoveRole(ctx, "viewer", "web")
 	if err != nil {
 		t.Fatalf("failed to remove role: %v", err)
 	}
 
 	// Verify role revoked
-	ok, err = userInTeam.Can(ctx, "read:articles")
+	ok, err = userInTeam.Can(ctx, "read:articles", "web")
 	if err != nil {
 		t.Fatalf("Can failed: %v", err)
 	}