feat(permissions): project member permission filter (#9757)

# Which Problems Are Solved

Add the possibility to filter project resources based on project member
roles.

# How the Problems Are Solved

Extend and refactor existing Pl/PgSQL functions to implement the
following:

- Solve O(n) complexity in returned resources IDs by returning a boolean
filter for instance level permissions.
- Individually permitted orgs are returned only if there was no instance
permission
- Individually permitted projects are returned only if there was no
instance permission
- Because of the multiple filter terms, use `INNER JOIN`s instead of
`WHERE` clauses.

# Additional Changes

- system permission function no longer query the organization view and
therefore can be `immutable`, giving big performance benefits for
frequently reused system users. (like our hosted login in Zitadel cloud)
- The permitted org and project functions are now defined as `stable`
because the don't modify on-disk data. This might give a small
performance gain
- The Pl/PgSQL functions are now tested using Go unit tests.

# Additional Context

- Depends on https://github.com/zitadel/zitadel/pull/9677
- Part of https://github.com/zitadel/zitadel/issues/9188
- Closes https://github.com/zitadel/zitadel/issues/9190

internal/query/permission.go

@@ -2,7 +2,6 @@ package query
 
 import (
 	"context"
-	"fmt"
 
 	sq "github.com/Masterminds/squirrel"
 	"github.com/zitadel/logging"
@@ -10,41 +9,66 @@ import (
 	"github.com/zitadel/zitadel/internal/api/authz"
 	"github.com/zitadel/zitadel/internal/database"
 	domain_pkg "github.com/zitadel/zitadel/internal/domain"
+	"github.com/zitadel/zitadel/internal/zerrors"
 )
 
 const (
-	// eventstore.permitted_orgs(instanceid text, userid text, system_user_perms JSONB, perm text, filter_org text)
-	wherePermittedOrgsExpr = "%s = ANY(eventstore.permitted_orgs(?, ?, ?, ?, ?))"
+	// eventstore.permitted_orgs(req_instance_id text, auth_user_id text, system_user_perms JSONB, perm text, filter_org text)
+	joinPermittedOrgsFunction = `INNER JOIN eventstore.permitted_orgs(?, ?, ?, ?, ?) permissions ON `
+
+	// eventstore.permitted_projects(req_instance_id text, auth_user_id text, system_user_perms JSONB, perm text, filter_org text)
+	joinPermittedProjectsFunction = `INNER JOIN eventstore.permitted_projects(?, ?, ?, ?, ?) permissions ON `
 )
 
+// permissionClauseBuilder is used to build the SQL clause for permission checks.
+// Don't use it directly, use the [PermissionClause] function with proper options instead.
 type permissionClauseBuilder struct {
 	orgIDColumn       Column
 	instanceID        string
 	userID            string
 	systemPermissions []authz.SystemUserPermissions
 	permission        string
-	orgID             string
-	connections       []sq.Eq
+
+	// optional fields
+	orgID           *string
+	projectIDColumn *Column
+	connections     []sq.Eq
 }
 
 func (b *permissionClauseBuilder) appendConnection(column string, value any) {
 	b.connections = append(b.connections, sq.Eq{column: value})
 }
 
-func (b *permissionClauseBuilder) clauses() sq.Or {
-	clauses := make(sq.Or, 1, len(b.connections)+1)
-	clauses[0] = sq.Expr(
-		fmt.Sprintf(wherePermittedOrgsExpr, b.orgIDColumn.identifier()),
+// joinFunction picks the correct SQL function and return the required arguments for that function.
+func (b *permissionClauseBuilder) joinFunction() (sql string, args []any) {
+	sql = joinPermittedOrgsFunction
+	if b.projectIDColumn != nil {
+		sql = joinPermittedProjectsFunction
+	}
+	return sql, []any{
 		b.instanceID,
 		b.userID,
 		database.NewJSONArray(b.systemPermissions),
 		b.permission,
 		b.orgID,
-	)
-	for _, include := range b.connections {
-		clauses = append(clauses, include)
 	}
-	return clauses
+}
+
+// joinConditions returns the conditions for the join,
+// which are dynamic based on the provided options.
+func (b *permissionClauseBuilder) joinConditions() sq.Or {
+	conditions := make(sq.Or, 2, len(b.connections)+3)
+	conditions[0] = sq.Expr("permissions.instance_permitted")
+	conditions[1] = sq.Expr(b.orgIDColumn.identifier() + " = ANY(permissions.org_ids)")
+	if b.projectIDColumn != nil {
+		conditions = append(conditions,
+			sq.Expr(b.projectIDColumn.identifier()+" = ANY(permissions.project_ids)"),
+		)
+	}
+	for _, c := range b.connections {
+		conditions = append(conditions, c)
+	}
+	return conditions
 }
 
 type PermissionOption func(b *permissionClauseBuilder)
@@ -52,6 +76,8 @@ type PermissionOption func(b *permissionClauseBuilder)
 // OwnedRowsPermissionOption allows rows to be returned of which the current user is the owner.
 // Even if the user does not have an explicit permission for the organization.
 // For example an authenticated user can always see his own user account.
+// This option may be provided multiple times to allow matching with multiple columns.
+// See [ConnectionPermissionOption] for more details.
 func OwnedRowsPermissionOption(userIDColumn Column) PermissionOption {
 	return func(b *permissionClauseBuilder) {
 		b.appendConnection(userIDColumn.identifier(), b.userID)
@@ -59,7 +85,10 @@ func OwnedRowsPermissionOption(userIDColumn Column) PermissionOption {
 }
 
 // ConnectionPermissionOption allows returning of rows where the value is matched.
-// Even if the user does not have an explicit permission for the organization.
+// Even if the user does not have an explicit permission for the resource.
+// Multiple connections may be provided.
+// Each connection is applied in a OR condition, so if previous permissions are not met,
+// matching rows are still returned for a later match.
 func ConnectionPermissionOption(column Column, value any) PermissionOption {
 	return func(b *permissionClauseBuilder) {
 		b.appendConnection(column.identifier(), value)
@@ -70,15 +99,28 @@ func ConnectionPermissionOption(column Column, value any) PermissionOption {
 // returned organizations, to the one used in the requested filters.
 func SingleOrgPermissionOption(queries []SearchQuery) PermissionOption {
 	return func(b *permissionClauseBuilder) {
-		b.orgID = findTextEqualsQuery(b.orgIDColumn, queries)
+		orgID, ok := findTextEqualsQuery(b.orgIDColumn, queries)
+		if ok {
+			b.orgID = &orgID
+		}
 	}
 }
 
-// PermissionClause sets a `WHERE` clause to query,
-// which filters returned rows the current authenticated user has the requested permission to.
+// WithProjectsPermissionOption sets an additional filter against the project ID column,
+// allowing for project specific permissions.
+func WithProjectsPermissionOption(projectIDColumn Column) PermissionOption {
+	return func(b *permissionClauseBuilder) {
+		b.projectIDColumn = &projectIDColumn
+	}
+}
+
+// PermissionClause builds a `INNER JOIN` clause which can be applied to a query builder.
+// It filters returned rows the current authenticated user has the requested permission to.
+// See permission_example_test.go for examples.
 //
-// Experimental: Work in progress. Currently only organization permissions are supported
-func PermissionClause(ctx context.Context, orgIDCol Column, permission string, options ...PermissionOption) sq.Or {
+// Experimental: Work in progress. Currently only organization and project permissions are supported
+// TODO: Add support for project grants.
+func PermissionClause(ctx context.Context, orgIDCol Column, permission string, options ...PermissionOption) (string, []any) {
 	ctxData := authz.GetCtxData(ctx)
 	b := &permissionClauseBuilder{
 		orgIDColumn:       orgIDCol,
@@ -97,10 +139,18 @@ func PermissionClause(ctx context.Context, orgIDCol Column, permission string, o
 		"system_user_permissions", b.systemPermissions,
 		"permission", b.permission,
 		"org_id", b.orgID,
-		"overrides", b.connections,
+		"project_id_column", b.projectIDColumn,
+		"connections", b.connections,
 	).Debug("permitted orgs check used")
 
-	return b.clauses()
+	sql, args := b.joinFunction()
+	conditions, conditionArgs, err := b.joinConditions().ToSql()
+	if err != nil {
+		// all cases are tested, no need to return an error.
+		// If an error does happen, it's a bug and not a user error.
+		panic(zerrors.ThrowInternal(err, "PERMISSION-OoS5o", "Errors.Internal"))
+	}
+	return sql + conditions, append(args, conditionArgs...)
 }
 
 // PermissionV2 checks are enabled when the feature flag is set and the permission check function is not nil.