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

cmd/defaults.yaml

@@ -607,6 +607,16 @@ EncryptionKeys:
   UserAgentCookieKeyID: "userAgentCookieKey" # ZITADEL_ENCRYPTIONKEYS_USERAGENTCOOKIEKEYID
 
 SystemAPIUsers:
+  - superuser:
+    Path: /path/to/superuser/key.pem
+    Memberships:
+      - MemberType: Organization
+        Roles: "ORG_OWNER"
+        AggregateID: "123456789012345678"
+      - MemberType: Project
+        Roles: "PROJECT_OWNER"
+
+
 # # Add keys for authentication of the systemAPI here:
 # # you can specify any name for the user, but they will have to match the `issuer` and `sub` claim in the JWT:
 # - superuser:

cmd/setup/53.go

@@ -33,5 +33,5 @@ func (mig *InitPermittedOrgsFunction53) Execute(ctx context.Context, _ eventstor
 }
 
 func (*InitPermittedOrgsFunction53) String() string {
-	return "53_init_permitted_orgs_function"
+	return "53_init_permitted_orgs_function_v2"
 }

cmd/setup/53/01-get-permissions-from-JSON.sql

@@ -1,23 +1,28 @@
+DROP FUNCTION IF EXISTS eventstore.check_system_user_perms;
 DROP FUNCTION IF EXISTS eventstore.get_system_permissions;
+DROP TYPE IF EXISTS eventstore.project_grant;
 
+
+/*
+	Function get_system_permissions unpacks an JSON array of system member permissions,
+	into a table format. Each array entry maps to one row representing a membership which
+	contained the req_permission.
+
+	[
+		{
+		"member_type": "IAM",
+		"aggregate_id": "310716990375453665",
+		"object_id": "",
+		"permissions": ["iam.read", "iam.write", "iam.policy.read"]
+		},
+		...
+	]
+
+	| member_type | aggregate_id         | object_id |
+	| "IAM"       | "310716990375453665" | null      |
+*/
 CREATE OR REPLACE FUNCTION eventstore.get_system_permissions(
     permissions_json JSONB
-    /*
-    [
-      {
-        "member_type": "System",
-        "aggregate_id": "",
-        "object_id": "",
-        "permissions": ["iam.read", "iam.write", "iam.polic.read"]
-      },
-      {
-        "member_type": "IAM",
-        "aggregate_id": "310716990375453665",
-        "object_id": "",
-        "permissions": ["iam.read", "iam.write", "iam.polic.read"]
-      }
-    ]
-    */
     , permm TEXT
 )
 RETURNS TABLE (
@@ -25,7 +30,7 @@ RETURNS TABLE (
     aggregate_id TEXT,
     object_id TEXT
 )
-  LANGUAGE 'plpgsql'
+  LANGUAGE 'plpgsql' IMMUTABLE
 AS $$
 BEGIN
     RETURN QUERY
@@ -37,7 +42,73 @@ BEGIN
         permission
         FROM jsonb_array_elements(permissions_json) AS perm
         CROSS JOIN jsonb_array_elements_text(perm->'permissions') AS permission) AS res
-        WHERE res. permission= permm;
+        WHERE res.permission = permm;
 END;
 $$;
 
+/*
+	Type project_grant is composite identifier using its project and grant IDs.
+*/
+CREATE TYPE eventstore.project_grant AS (
+    project_id TEXT -- mapped from a permission's aggregate_id
+    , grant_id TEXT -- mapped from a permission's object_id
+);
+
+/*
+	Function check_system_user_perms uses system member permissions to establish
+	on which organization, project or project grant the user has the requested permission.
+	The permission can also apply to the complete instance when a IAM membership matches
+	the requested instance ID, or through system membership.
+
+	See eventstore.get_system_permissions() on the supported JSON format.
+*/
+CREATE OR REPLACE FUNCTION eventstore.check_system_user_perms(
+     system_user_perms JSONB
+    , req_instance_id TEXT
+    , perm TEXT
+
+    , instance_permitted OUT BOOLEAN
+    , org_ids OUT TEXT[]
+    , project_ids OUT TEXT[]
+    , project_grants OUT eventstore.project_grant[]
+)
+	LANGUAGE 'plpgsql' IMMUTABLE
+AS $$
+BEGIN
+	-- make sure no nulls are returned
+	instance_permitted := FALSE;
+	org_ids := ARRAY[]::TEXT[];
+	project_ids := ARRAY[]::TEXT[];
+	project_grants := ARRAY[]::eventstore.project_grant[];
+	DECLARE
+	    p RECORD;
+	BEGIN
+        FOR p IN SELECT member_type, aggregate_id, object_id
+	        FROM eventstore.get_system_permissions(system_user_perms, perm)
+	    LOOP
+	       CASE p.member_type
+	            WHEN 'System' THEN
+	                instance_permitted := TRUE;
+	                RETURN;
+	            WHEN 'IAM' THEN
+	                IF p.aggregate_id = req_instance_id THEN
+	                    instance_permitted := TRUE;
+	                    RETURN;
+	                END IF;
+	            WHEN 'Organization' THEN
+	                IF p.aggregate_id != '' THEN
+	                    org_ids := array_append(org_ids, p.aggregate_id);
+	                END IF;
+	            WHEN 'Project' THEN
+	                IF p.aggregate_id != '' THEN
+	                    project_ids := array_append(project_ids, p.aggregate_id);
+	                END IF;
+	            WHEN 'ProjectGrant' THEN
+	                IF p.aggregate_id != '' THEN
+	                    project_grants := array_append(project_grants, ROW(p.aggregate_id, p.object_id)::eventstore.project_grant);
+	                END IF;
+	        END CASE;
+	    END LOOP;
+	END;
+END;
+$$;

cmd/setup/53/02-permitted_orgs_function.sql

@@ -1,144 +1,71 @@
-DROP FUNCTION IF EXISTS eventstore.check_system_user_perms;
+DROP FUNCTION IF EXISTS eventstore.permitted_orgs;
+DROP FUNCTION IF EXISTS eventstore.find_roles;
 
-CREATE OR REPLACE FUNCTION eventstore.check_system_user_perms(
-     system_user_perms JSONB
+-- find_roles finds all roles containing the permission
+CREATE OR REPLACE FUNCTION eventstore.find_roles(
+    req_instance_id TEXT
     , perm TEXT
-    , filter_orgs TEXT
 
-    , org_ids OUT TEXT[]
+    , roles OUT TEXT[]
 )
-	LANGUAGE 'plpgsql'
+LANGUAGE 'plpgsql' STABLE
 AS $$
 BEGIN
-
-    WITH found_permissions(member_type, aggregate_id, object_id ) AS (
-      SELECT * FROM eventstore.get_system_permissions(
-          system_user_perms,
-          perm)
-    )
-
-    SELECT array_agg(DISTINCT o.org_id) INTO org_ids
-      FROM eventstore.instance_orgs o, found_permissions
-      WHERE
-        CASE WHEN (SELECT TRUE WHERE found_permissions.member_type = 'System' LIMIT 1) THEN
-          TRUE
-        WHEN (SELECT TRUE WHERE found_permissions.member_type = 'IAM' LIMIT 1) THEN
-          -- aggregate_id not present
-          CASE WHEN (SELECT TRUE WHERE '' = ANY (
-                              (
-                                SELECT array_agg(found_permissions.aggregate_id)
-                                  FROM found_permissions
-                                  WHERE member_type = 'IAM'
-                                  GROUP BY member_type
-                                  LIMIT 1
-                              )::TEXT[])) THEN
-            TRUE
-          -- aggregate_id is present
-          ELSE 
-            o.instance_id = ANY (
-                            (
-                              SELECT array_agg(found_permissions.aggregate_id)
-                                FROM found_permissions
-                                WHERE member_type = 'IAM'
-                                GROUP BY member_type
-                                LIMIT 1
-                            )::TEXT[])
-          END
-        WHEN (SELECT TRUE WHERE found_permissions.member_type = 'Organization' LIMIT 1) THEN
-          -- aggregate_id not present
-          CASE WHEN (SELECT TRUE WHERE '' = ANY (
-                              (
-                                SELECT array_agg(found_permissions.aggregate_id)
-                                  FROM found_permissions
-                                  WHERE member_type = 'Organization'
-                                  GROUP BY member_type
-                                  LIMIT 1
-                              )::TEXT[])) THEN
-            TRUE
-          -- aggregate_id is present
-          ELSE 
-            o.org_id = ANY (
-                        (
-                          SELECT array_agg(found_permissions.aggregate_id)
-                            FROM found_permissions
-                            WHERE member_type = 'Organization'
-                            GROUP BY member_type
-                            LIMIT 1
-                        )::TEXT[])
-          END
-        END
-        AND
-        CASE WHEN filter_orgs != ''
-        THEN o.org_id IN (filter_orgs) 
-        ELSE TRUE END
-      LIMIT 1;
+    SELECT array_agg(rp.role) INTO roles
+    FROM eventstore.role_permissions rp
+    WHERE rp.instance_id = req_instance_id
+    AND rp.permission = perm;
 END;
 $$;
 
-
-DROP FUNCTION IF EXISTS eventstore.permitted_orgs;
-
 CREATE OR REPLACE FUNCTION eventstore.permitted_orgs(
-    instanceId TEXT
-    , userId TEXT
+    req_instance_id TEXT
+    , auth_user_id TEXT
     , system_user_perms JSONB
     , perm TEXT
-    , filter_orgs TEXT
+    , filter_org TEXT
 
+    , instance_permitted OUT BOOLEAN
     , org_ids OUT TEXT[]
 )
-	LANGUAGE 'plpgsql'
+	LANGUAGE 'plpgsql' STABLE
 AS $$
 BEGIN
-
-  -- if system user
-  IF system_user_perms IS NOT NULL THEN
-    org_ids := eventstore.check_system_user_perms(system_user_perms, perm, filter_orgs);
-  -- if human/machine user
-  ELSE
+    -- if system user
+    IF system_user_perms IS NOT NULL THEN
+        SELECT p.instance_permitted, p.org_ids INTO instance_permitted, org_ids
+        FROM eventstore.check_system_user_perms(system_user_perms, req_instance_id, perm) p;
+        RETURN;
+    END IF;
+  
+    -- if human/machine user
     DECLARE
-      matched_roles TEXT[]; -- roles containing permission
-    BEGIN
-
-      SELECT array_agg(rp.role) INTO matched_roles
-      FROM eventstore.role_permissions rp
-      WHERE rp.instance_id = instanceId
-      AND rp.permission = perm;
-
-      -- First try if the permission was granted thru an instance-level role
-      DECLARE
-        has_instance_permission bool;
-      BEGIN
-        SELECT true INTO has_instance_permission
-          FROM eventstore.instance_members im
-          WHERE im.role = ANY(matched_roles)
-          AND im.instance_id = instanceId
-          AND im.user_id = userId
-          LIMIT 1;
+    	matched_roles TEXT[] := eventstore.find_roles(req_instance_id, perm);
+	BEGIN
+        -- First try if the permission was granted thru an instance-level role
+        SELECT true INTO instance_permitted
+            FROM eventstore.instance_members im
+            WHERE im.role = ANY(matched_roles)
+            AND im.instance_id = req_instance_id
+            AND im.user_id = auth_user_id
+            LIMIT 1;
         
-        IF has_instance_permission THEN
-          -- Return all organizations or only those in filter_orgs
-          SELECT array_agg(o.org_id) INTO org_ids
-            FROM eventstore.instance_orgs o
-            WHERE o.instance_id = instanceId
-            AND CASE WHEN filter_orgs != ''
-              THEN o.org_id IN (filter_orgs) 
-              ELSE TRUE END;
-          RETURN;
+        org_ids := ARRAY[]::TEXT[];
+        IF instance_permitted THEN
+            RETURN;
         END IF;
-      END;
-      
-      -- Return the organizations where permission were granted thru org-level roles
-      SELECT array_agg(sub.org_id) INTO org_ids
-      FROM (
-        SELECT DISTINCT om.org_id
-        FROM eventstore.org_members om
-        WHERE om.role = ANY(matched_roles)
-        AND om.instance_id = instanceID
-        AND om.user_id = userId
-      ) AS sub;
+        instance_permitted := FALSE;
+
+        -- Return the organizations where permission were granted thru org-level roles
+        SELECT array_agg(sub.org_id) INTO org_ids
+        FROM (
+            SELECT DISTINCT om.org_id
+            FROM eventstore.org_members om
+            WHERE om.role = ANY(matched_roles)
+            AND om.instance_id = req_instance_id
+            AND om.user_id = auth_user_id
+            AND (filter_org IS NULL OR om.org_id = filter_org)
+        ) AS sub;
     END;
-  END IF;
 END;
 $$;
-

cmd/setup/53/03-permitted_projects_func.sql

@@ -0,0 +1,58 @@
+-- recreate the view to include the resource_owner
+CREATE OR REPLACE VIEW eventstore.project_members AS
+SELECT instance_id, aggregate_id as project_id, object_id as user_id, text_value as role, resource_owner as org_id
+FROM eventstore.fields
+WHERE aggregate_type = 'project'
+AND object_type = 'project_member_role'
+AND field_name = 'project_role';
+
+DROP FUNCTION IF EXISTS eventstore.permitted_projects;
+
+CREATE OR REPLACE FUNCTION eventstore.permitted_projects(
+    req_instance_id TEXT
+    , auth_user_id TEXT
+    , system_user_perms JSONB
+    , perm TEXT
+    , filter_org TEXT
+
+    , instance_permitted OUT BOOLEAN
+    , org_ids OUT TEXT[]
+    , project_ids OUT TEXT[]
+)
+	LANGUAGE 'plpgsql' STABLE
+AS $$
+BEGIN
+    -- if system user
+    IF system_user_perms IS NOT NULL THEN
+        SELECT p.instance_permitted, p.org_ids INTO instance_permitted, org_ids, project_ids
+        FROM eventstore.check_system_user_perms(system_user_perms, req_instance_id, perm) p;
+        RETURN;
+    END IF;
+
+    -- if human/machine user
+    SELECT * FROM eventstore.permitted_orgs(
+        req_instance_id
+        , auth_user_id
+        , system_user_perms
+        , perm
+        , filter_org
+    ) INTO instance_permitted, org_ids;
+    IF instance_permitted THEN
+        RETURN;
+    END IF;
+	DECLARE
+    	matched_roles TEXT[] := eventstore.find_roles(req_instance_id, perm);
+	BEGIN
+	    -- Get the projects where permission were granted thru project-level roles
+	    SELECT array_agg(sub.project_id) INTO project_ids
+	    FROM (
+	        SELECT DISTINCT pm.project_id
+	        FROM eventstore.project_members pm
+	        WHERE pm.role = ANY(matched_roles)
+	        AND pm.instance_id = req_instance_id
+	        AND pm.user_id = auth_user_id
+	        AND (filter_org IS NULL OR pm.org_id = filter_org)
+	    ) AS sub;
+	END;
+END;
+$$;

cmd/setup/integration_test/permission_test.go

@@ -0,0 +1,871 @@
+//go:build integration
+
+package setup_test
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgtype"
+	"github.com/muhlemmer/gu"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/zitadel/zitadel/internal/api/authz"
+	"github.com/zitadel/zitadel/internal/database"
+	"github.com/zitadel/zitadel/internal/eventstore"
+	"github.com/zitadel/zitadel/internal/repository/instance"
+	"github.com/zitadel/zitadel/internal/repository/org"
+	"github.com/zitadel/zitadel/internal/repository/permission"
+	"github.com/zitadel/zitadel/internal/repository/project"
+)
+
+func TestGetSystemPermissions(t *testing.T) {
+	const query = "SELECT * FROM eventstore.get_system_permissions($1, $2);"
+	t.Parallel()
+	permissions := []authz.SystemUserPermissions{
+		{
+			MemberType:  authz.MemberTypeSystem,
+			Permissions: []string{"iam.read", "iam.write", "iam.policy.read"},
+		},
+		{
+			MemberType:  authz.MemberTypeIAM,
+			AggregateID: "instanceID",
+			Permissions: []string{"iam.read", "iam.write", "iam.policy.read", "org.read", "project.read", "project.write"},
+		},
+		{
+			MemberType:  authz.MemberTypeOrganization,
+			AggregateID: "orgID",
+			Permissions: []string{"org.read", "org.write", "org.policy.read", "project.read", "project.write"},
+		},
+		{
+			MemberType:  authz.MemberTypeProject,
+			AggregateID: "projectID",
+			Permissions: []string{"project.read", "project.write"},
+		},
+		{
+			MemberType:  authz.MemberTypeProjectGrant,
+			AggregateID: "projectID",
+			ObjectID:    "grantID",
+			Permissions: []string{"project.read", "project.write"},
+		},
+	}
+	type result struct {
+		MemberType  authz.MemberType
+		AggregateID string
+		ObjectID    string
+	}
+	tests := []struct {
+		permm string
+		want  []result
+	}{
+		{
+			permm: "iam.read",
+			want: []result{
+				{
+					MemberType: authz.MemberTypeSystem,
+				},
+				{
+					MemberType:  authz.MemberTypeIAM,
+					AggregateID: "instanceID",
+				},
+			},
+		},
+		{
+			permm: "org.read",
+			want: []result{
+				{
+					MemberType:  authz.MemberTypeIAM,
+					AggregateID: "instanceID",
+				},
+				{
+					MemberType:  authz.MemberTypeOrganization,
+					AggregateID: "orgID",
+				},
+			},
+		},
+		{
+			permm: "project.write",
+			want: []result{
+				{
+					MemberType:  authz.MemberTypeIAM,
+					AggregateID: "instanceID",
+				},
+				{
+					MemberType:  authz.MemberTypeOrganization,
+					AggregateID: "orgID",
+				},
+				{
+					MemberType:  authz.MemberTypeProject,
+					AggregateID: "projectID",
+				},
+				{
+					MemberType:  authz.MemberTypeProjectGrant,
+					AggregateID: "projectID",
+					ObjectID:    "grantID",
+				},
+			},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.permm, func(t *testing.T) {
+			t.Parallel()
+			rows, err := dbPool.Query(CTX, query, database.NewJSONArray(permissions), tt.permm)
+			require.NoError(t, err)
+			got, err := pgx.CollectRows(rows, pgx.RowToStructByPos[result])
+			require.NoError(t, err)
+			assert.ElementsMatch(t, tt.want, got)
+		})
+	}
+}
+
+func TestCheckSystemUserPerms(t *testing.T) {
+	// Use JSON because of the composite project_grants SQL type
+	const query = "SELECT row_to_json(eventstore.check_system_user_perms($1, $2, $3));"
+	t.Parallel()
+	type args struct {
+		reqInstanceID string
+		permissions   []authz.SystemUserPermissions
+		permm         string
+	}
+	tests := []struct {
+		name string
+		args args
+		want string
+	}{
+		{
+			name: "iam.read, instance permitted from system",
+			args: args{
+				reqInstanceID: "instanceID",
+				permissions: []authz.SystemUserPermissions{
+					{
+						MemberType:  authz.MemberTypeSystem,
+						Permissions: []string{"iam.read", "iam.write", "iam.policy.read"},
+					},
+					{
+						MemberType:  authz.MemberTypeIAM,
+						AggregateID: "instanceID",
+						Permissions: []string{"iam.read", "iam.write", "iam.policy.read", "org.read"},
+					},
+					{
+						MemberType:  authz.MemberTypeOrganization,
+						AggregateID: "orgID",
+						Permissions: []string{"org.read", "org.write", "org.policy.read", "project.read", "project.write"},
+					},
+					{
+						MemberType:  authz.MemberTypeProject,
+						AggregateID: "projectID",
+						Permissions: []string{"project.read", "project.write"},
+					},
+					{
+						MemberType:  authz.MemberTypeProjectGrant,
+						AggregateID: "projectID",
+						ObjectID:    "grantID",
+						Permissions: []string{"project.read", "project.write"},
+					},
+				},
+				permm: "iam.read",
+			},
+			want: `{
+				"instance_permitted": true,
+				"org_ids": [],
+				"project_grants": [],
+				"project_ids": []
+			}`,
+		},
+		{
+			name: "org.read, instance permitted",
+			args: args{
+				reqInstanceID: "instanceID",
+				permissions: []authz.SystemUserPermissions{
+					{
+						MemberType:  authz.MemberTypeSystem,
+						Permissions: []string{"iam.read", "iam.write", "iam.policy.read"},
+					},
+					{
+						MemberType:  authz.MemberTypeIAM,
+						AggregateID: "instanceID",
+						Permissions: []string{"iam.read", "iam.write", "iam.policy.read", "org.read"},
+					},
+					{
+						MemberType:  authz.MemberTypeOrganization,
+						AggregateID: "orgID",
+						Permissions: []string{"org.read", "org.write", "org.policy.read", "project.read", "project.write"},
+					},
+					{
+						MemberType:  authz.MemberTypeProject,
+						AggregateID: "projectID",
+						Permissions: []string{"project.read", "project.write"},
+					},
+					{
+						MemberType:  authz.MemberTypeProjectGrant,
+						AggregateID: "projectID",
+						ObjectID:    "grantID",
+						Permissions: []string{"project.read", "project.write"},
+					},
+				},
+				permm: "org.read",
+			},
+			want: `{
+				"instance_permitted": true,
+				"org_ids": [],
+				"project_grants": [],
+				"project_ids": []
+			}`,
+		},
+		{
+			name: "project.read, org ID and project ID permitted",
+			args: args{
+				reqInstanceID: "instanceID",
+				permissions: []authz.SystemUserPermissions{
+					{
+						MemberType:  authz.MemberTypeSystem,
+						Permissions: []string{"iam.read", "iam.write", "iam.policy.read"},
+					},
+					{
+						MemberType:  authz.MemberTypeIAM,
+						AggregateID: "instanceID",
+						Permissions: []string{"iam.read", "iam.write", "iam.policy.read", "org.read"},
+					},
+					{
+						MemberType:  authz.MemberTypeOrganization,
+						AggregateID: "orgID",
+						Permissions: []string{"org.read", "org.write", "org.policy.read", "project.read", "project.write"},
+					},
+					{
+						MemberType:  authz.MemberTypeProject,
+						AggregateID: "projectID",
+						Permissions: []string{"project.read", "project.write"},
+					},
+					{
+						MemberType:  authz.MemberTypeProjectGrant,
+						AggregateID: "projectID",
+						ObjectID:    "grantID",
+						Permissions: []string{"project_grant.read", "project_grant.write"},
+					},
+				},
+				permm: "project.read",
+			},
+			want: `{
+				"instance_permitted": false,
+				"org_ids": ["orgID"],
+				"project_ids": ["projectID"],
+				"project_grants": []
+			}`,
+		},
+		{
+			name: "project_grant.read, project grant ID permitted",
+			args: args{
+				reqInstanceID: "instanceID",
+				permissions: []authz.SystemUserPermissions{
+					{
+						MemberType:  authz.MemberTypeSystem,
+						Permissions: []string{"iam.read", "iam.write", "iam.policy.read"},
+					},
+					{
+						MemberType:  authz.MemberTypeIAM,
+						AggregateID: "instanceID",
+						Permissions: []string{"iam.read", "iam.write", "iam.policy.read", "org.read"},
+					},
+					{
+						MemberType:  authz.MemberTypeOrganization,
+						AggregateID: "orgID",
+						Permissions: []string{"org.read", "org.write", "org.policy.read", "project.read", "project.write"},
+					},
+					{
+						MemberType:  authz.MemberTypeProject,
+						AggregateID: "projectID",
+						Permissions: []string{"project.read", "project.write"},
+					},
+					{
+						MemberType:  authz.MemberTypeProjectGrant,
+						AggregateID: "projectID",
+						ObjectID:    "grantID",
+						Permissions: []string{"project_grant.read", "project_grant.write"},
+					},
+				},
+				permm: "project_grant.read",
+			},
+			want: `{
+				"instance_permitted": false,
+				"org_ids": [],
+				"project_ids": [],
+				"project_grants": [
+					{
+						"project_id": "projectID",
+						"grant_id": "grantID"
+					}
+				]
+			}`,
+		},
+		{
+			name: "instance without aggregate ID",
+			args: args{
+				reqInstanceID: "instanceID",
+				permissions: []authz.SystemUserPermissions{
+					{
+						MemberType:  authz.MemberTypeIAM,
+						AggregateID: "",
+						Permissions: []string{"foo.bar", "bar.foo"},
+					},
+				},
+				permm: "foo.bar",
+			},
+			want: `{
+				"instance_permitted": false,
+				"org_ids": [],
+				"project_ids": [],
+				"project_grants": []
+			}`,
+		},
+		{
+			name: "wrong instance ID",
+			args: args{
+				reqInstanceID: "instanceID",
+				permissions: []authz.SystemUserPermissions{
+					{
+						MemberType:  authz.MemberTypeIAM,
+						AggregateID: "wrong",
+						Permissions: []string{"foo.bar", "bar.foo"},
+					},
+				},
+				permm: "foo.bar",
+			},
+			want: `{
+				"instance_permitted": false,
+				"org_ids": [],
+				"project_ids": [],
+				"project_grants": []
+			}`,
+		},
+		{
+			name: "permission on other instance",
+			args: args{
+				reqInstanceID: "instanceID",
+				permissions: []authz.SystemUserPermissions{
+					{
+						MemberType:  authz.MemberTypeIAM,
+						AggregateID: "instanceID",
+						Permissions: []string{"bar.foo"},
+					},
+					{
+						MemberType:  authz.MemberTypeIAM,
+						AggregateID: "wrong",
+						Permissions: []string{"foo.bar"},
+					},
+				},
+				permm: "foo.bar",
+			},
+			want: `{
+				"instance_permitted": false,
+				"org_ids": [],
+				"project_ids": [],
+				"project_grants": []
+			}`,
+		},
+		{
+			name: "org ID missing",
+			args: args{
+				reqInstanceID: "instanceID",
+				permissions: []authz.SystemUserPermissions{
+					{
+						MemberType:  authz.MemberTypeOrganization,
+						AggregateID: "",
+						Permissions: []string{"foo.bar"},
+					},
+				},
+				permm: "foo.bar",
+			},
+			want: `{
+				"instance_permitted": false,
+				"org_ids": [],
+				"project_ids": [],
+				"project_grants": []
+			}`,
+		},
+		{
+			name: "multiple org IDs",
+			args: args{
+				reqInstanceID: "instanceID",
+				permissions: []authz.SystemUserPermissions{
+					{
+						MemberType:  authz.MemberTypeOrganization,
+						AggregateID: "Org1",
+						Permissions: []string{"foo.bar"},
+					},
+					{
+						MemberType:  authz.MemberTypeOrganization,
+						AggregateID: "Org2",
+						Permissions: []string{"foo.bar"},
+					},
+				},
+				permm: "foo.bar",
+			},
+			want: `{
+				"instance_permitted": false,
+				"org_ids": ["Org1", "Org2"],
+				"project_ids": [],
+				"project_grants": []
+			}`,
+		},
+		{
+			name: "project ID missing",
+			args: args{
+				reqInstanceID: "instanceID",
+				permissions: []authz.SystemUserPermissions{
+					{
+						MemberType:  authz.MemberTypeProject,
+						AggregateID: "",
+						Permissions: []string{"foo.bar"},
+					},
+				},
+				permm: "foo.bar",
+			},
+			want: `{
+				"instance_permitted": false,
+				"org_ids": [],
+				"project_ids": [],
+				"project_grants": []
+			}`,
+		},
+		{
+			name: "multiple project IDs",
+			args: args{
+				reqInstanceID: "instanceID",
+				permissions: []authz.SystemUserPermissions{
+					{
+						MemberType:  authz.MemberTypeProject,
+						AggregateID: "P1",
+						Permissions: []string{"foo.bar"},
+					},
+					{
+						MemberType:  authz.MemberTypeProject,
+						AggregateID: "P2",
+						Permissions: []string{"foo.bar"},
+					},
+				},
+				permm: "foo.bar",
+			},
+			want: `{
+				"instance_permitted": false,
+				"org_ids": [],
+				"project_ids": ["P1", "P2"],
+				"project_grants": []
+			}`,
+		},
+		{
+			name: "project grant ID missing",
+			args: args{
+				reqInstanceID: "instanceID",
+				permissions: []authz.SystemUserPermissions{
+					{
+						MemberType:  authz.MemberTypeProjectGrant,
+						AggregateID: "",
+						ObjectID:    "",
+						Permissions: []string{"foo.bar"},
+					},
+				},
+				permm: "foo.bar",
+			},
+			want: `{
+				"instance_permitted": false,
+				"org_ids": [],
+				"project_ids": [],
+				"project_grants": []
+			}`,
+		},
+		{
+			name: "multiple project IDs",
+			args: args{
+				reqInstanceID: "instanceID",
+				permissions: []authz.SystemUserPermissions{
+					{
+						MemberType:  authz.MemberTypeProjectGrant,
+						AggregateID: "P1",
+						ObjectID:    "O1",
+						Permissions: []string{"foo.bar"},
+					},
+					{
+						MemberType:  authz.MemberTypeProjectGrant,
+						AggregateID: "P2",
+						ObjectID:    "O2",
+						Permissions: []string{"foo.bar"},
+					},
+				},
+				permm: "foo.bar",
+			},
+			want: `{
+				"instance_permitted": false,
+				"org_ids": [],
+				"project_ids": [],
+				"project_grants": [
+					{
+						"project_id": "P1",
+						"grant_id": "O1"
+					},
+					{
+						"project_id": "P2",
+						"grant_id": "O2"
+					}
+				]
+			}`,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			rows, err := dbPool.Query(CTX, query, database.NewJSONArray(tt.args.permissions), tt.args.reqInstanceID, tt.args.permm)
+			require.NoError(t, err)
+			got, err := pgx.CollectOneRow(rows, pgx.RowTo[string])
+			require.NoError(t, err)
+			assert.JSONEq(t, tt.want, got)
+		})
+	}
+}
+
+const (
+	instanceID = "instanceID"
+	orgID      = "orgID"
+	projectID  = "projectID"
+)
+
+func TestPermittedOrgs(t *testing.T) {
+	t.Parallel()
+
+	tx, err := dbPool.Begin(CTX)
+	require.NoError(t, err)
+	defer tx.Rollback(CTX)
+
+	// Insert a couple of deterministic field rows to test the function.
+	// Data will not persist, because the transaction is rolled back.
+	createRolePermission(t, tx, "IAM_OWNER", []string{"org.write", "org.read"})
+	createRolePermission(t, tx, "ORG_OWNER", []string{"org.write", "org.read"})
+	createMember(t, tx, instance.AggregateType, "instance_user")
+	createMember(t, tx, org.AggregateType, "org_user")
+
+	const query = "SELECT instance_permitted, org_ids FROM eventstore.permitted_orgs($1,$2,$3,$4,$5);"
+	type args struct {
+		reqInstanceID   string
+		authUserID      string
+		systemUserPerms []authz.SystemUserPermissions
+		perm            string
+		filterOrg       *string
+	}
+	type result struct {
+		InstancePermitted bool
+		OrgIDs            pgtype.FlatArray[string]
+	}
+	tests := []struct {
+		name string
+		args args
+		want result
+	}{
+		{
+			name: "system user, instance",
+			args: args{
+				reqInstanceID: instanceID,
+				systemUserPerms: []authz.SystemUserPermissions{{
+					MemberType:  authz.MemberTypeSystem,
+					Permissions: []string{"org.write", "org.read"},
+				}},
+				perm: "org.read",
+			},
+			want: result{
+				InstancePermitted: true,
+			},
+		},
+		{
+			name: "system user, orgs",
+			args: args{
+				reqInstanceID: instanceID,
+				systemUserPerms: []authz.SystemUserPermissions{{
+					MemberType:  authz.MemberTypeOrganization,
+					AggregateID: orgID,
+					Permissions: []string{"org.read", "org.write", "org.policy.read", "project.read", "project.write"},
+				}},
+				perm: "org.read",
+			},
+			want: result{
+				OrgIDs: pgtype.FlatArray[string]{orgID},
+			},
+		},
+		{
+			name: "instance member",
+			args: args{
+				reqInstanceID: instanceID,
+				authUserID:    "instance_user",
+				perm:          "org.read",
+			},
+			want: result{
+				InstancePermitted: true,
+			},
+		},
+		{
+			name: "org member",
+			args: args{
+				reqInstanceID: instanceID,
+				authUserID:    "org_user",
+				perm:          "org.read",
+			},
+			want: result{
+				OrgIDs: pgtype.FlatArray[string]{orgID},
+			},
+		},
+		{
+			name: "org member, filter",
+			args: args{
+				reqInstanceID: instanceID,
+				authUserID:    "org_user",
+				perm:          "org.read",
+				filterOrg:     gu.Ptr(orgID),
+			},
+			want: result{
+				OrgIDs: pgtype.FlatArray[string]{orgID},
+			},
+		},
+		{
+			name: "org member, filter wrong org",
+			args: args{
+				reqInstanceID: instanceID,
+				authUserID:    "org_user",
+				perm:          "org.read",
+				filterOrg:     gu.Ptr("foobar"),
+			},
+			want: result{},
+		},
+		{
+			name: "no permission",
+			args: args{
+				reqInstanceID: instanceID,
+				authUserID:    "foobar",
+				perm:          "org.read",
+				filterOrg:     gu.Ptr(orgID),
+			},
+			want: result{},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			rows, err := tx.Query(CTX, query, tt.args.reqInstanceID, tt.args.authUserID, database.NewJSONArray(tt.args.systemUserPerms), tt.args.perm, tt.args.filterOrg)
+			require.NoError(t, err)
+			got, err := pgx.CollectExactlyOneRow(rows, pgx.RowToStructByPos[result])
+			require.NoError(t, err)
+			assert.Equal(t, tt.want.InstancePermitted, got.InstancePermitted)
+			assert.ElementsMatch(t, tt.want.OrgIDs, got.OrgIDs)
+		})
+	}
+}
+
+func TestPermittedProjects(t *testing.T) {
+	t.Parallel()
+
+	tx, err := dbPool.Begin(CTX)
+	require.NoError(t, err)
+	defer tx.Rollback(CTX)
+
+	// Insert a couple of deterministic field rows to test the function.
+	// Data will not persist, because the transaction is rolled back.
+	createRolePermission(t, tx, "IAM_OWNER", []string{"project.write", "project.read"})
+	createRolePermission(t, tx, "ORG_OWNER", []string{"project.write", "project.read"})
+	createRolePermission(t, tx, "PROJECT_OWNER", []string{"project.write", "project.read"})
+	createMember(t, tx, instance.AggregateType, "instance_user")
+	createMember(t, tx, org.AggregateType, "org_user")
+	createMember(t, tx, project.AggregateType, "project_user")
+
+	const query = "SELECT instance_permitted, org_ids, project_ids FROM eventstore.permitted_projects($1,$2,$3,$4,$5);"
+	type args struct {
+		reqInstanceID   string
+		authUserID      string
+		systemUserPerms []authz.SystemUserPermissions
+		perm            string
+		filterOrg       *string
+	}
+	type result struct {
+		InstancePermitted bool
+		OrgIDs            pgtype.FlatArray[string]
+		ProjectIDs        pgtype.FlatArray[string]
+	}
+	tests := []struct {
+		name string
+		args args
+		want result
+	}{
+		{
+			name: "system user, instance",
+			args: args{
+				reqInstanceID: instanceID,
+				systemUserPerms: []authz.SystemUserPermissions{{
+					MemberType:  authz.MemberTypeSystem,
+					Permissions: []string{"project.write", "project.read"},
+				}},
+				perm: "project.read",
+			},
+			want: result{
+				InstancePermitted: true,
+			},
+		},
+		{
+			name: "system user, orgs",
+			args: args{
+				reqInstanceID: instanceID,
+				systemUserPerms: []authz.SystemUserPermissions{{
+					MemberType:  authz.MemberTypeOrganization,
+					AggregateID: orgID,
+					Permissions: []string{"project.read", "project.write"},
+				}},
+				perm: "project.read",
+			},
+			want: result{
+				OrgIDs: pgtype.FlatArray[string]{orgID},
+			},
+		},
+		{
+			name: "system user, projects",
+			args: args{
+				reqInstanceID: instanceID,
+				systemUserPerms: []authz.SystemUserPermissions{{
+					MemberType:  authz.MemberTypeProject,
+					AggregateID: projectID,
+					Permissions: []string{"project.read", "project.write"},
+				}},
+				perm: "project.read",
+			},
+			want: result{
+				ProjectIDs: pgtype.FlatArray[string]{projectID},
+			},
+		},
+		{
+			name: "system user, org and project",
+			args: args{
+				reqInstanceID: instanceID,
+				systemUserPerms: []authz.SystemUserPermissions{
+					{
+						MemberType:  authz.MemberTypeOrganization,
+						AggregateID: orgID,
+						Permissions: []string{"project.read", "project.write"},
+					},
+					{
+						MemberType:  authz.MemberTypeProject,
+						AggregateID: projectID,
+						Permissions: []string{"project.read", "project.write"},
+					},
+				},
+				perm: "project.read",
+			},
+			want: result{
+				OrgIDs:     pgtype.FlatArray[string]{orgID},
+				ProjectIDs: pgtype.FlatArray[string]{projectID},
+			},
+		},
+		{
+			name: "instance member",
+			args: args{
+				reqInstanceID: instanceID,
+				authUserID:    "instance_user",
+				perm:          "project.read",
+			},
+			want: result{
+				InstancePermitted: true,
+			},
+		},
+		{
+			name: "org member",
+			args: args{
+				reqInstanceID: instanceID,
+				authUserID:    "org_user",
+				perm:          "project.read",
+			},
+			want: result{
+				InstancePermitted: false,
+				OrgIDs:            pgtype.FlatArray[string]{orgID},
+			},
+		},
+		{
+			name: "org member, filter",
+			args: args{
+				reqInstanceID: instanceID,
+				authUserID:    "org_user",
+				perm:          "project.read",
+				filterOrg:     gu.Ptr(orgID),
+			},
+			want: result{
+				InstancePermitted: false,
+				OrgIDs:            pgtype.FlatArray[string]{orgID},
+			},
+		},
+		{
+			name: "org member, filter wrong org",
+			args: args{
+				reqInstanceID: instanceID,
+				authUserID:    "org_user",
+				perm:          "project.read",
+				filterOrg:     gu.Ptr("foobar"),
+			},
+			want: result{},
+		},
+		{
+			name: "project member",
+			args: args{
+				reqInstanceID: instanceID,
+				authUserID:    "project_user",
+				perm:          "project.read",
+			},
+			want: result{
+				ProjectIDs: pgtype.FlatArray[string]{projectID},
+			},
+		},
+		{
+			name: "no permission",
+			args: args{
+				reqInstanceID: instanceID,
+				authUserID:    "foobar",
+				perm:          "project.read",
+				filterOrg:     gu.Ptr(orgID),
+			},
+			want: result{},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			rows, err := tx.Query(CTX, query, tt.args.reqInstanceID, tt.args.authUserID, database.NewJSONArray(tt.args.systemUserPerms), tt.args.perm, tt.args.filterOrg)
+			require.NoError(t, err)
+			got, err := pgx.CollectExactlyOneRow(rows, pgx.RowToStructByPos[result])
+			require.NoError(t, err)
+			assert.Equal(t, tt.want.InstancePermitted, got.InstancePermitted)
+			assert.ElementsMatch(t, tt.want.OrgIDs, got.OrgIDs)
+		})
+	}
+}
+
+func createRolePermission(t *testing.T, tx pgx.Tx, role string, permissions []string) {
+	for _, perm := range permissions {
+		createTestField(t, tx, instanceID, permission.AggregateType, instanceID, "role_permission", role, "permission", perm)
+	}
+}
+
+func createMember(t *testing.T, tx pgx.Tx, aggregateType eventstore.AggregateType, userID string) {
+	var err error
+	switch aggregateType {
+	case instance.AggregateType:
+		createTestField(t, tx, instanceID, aggregateType, instanceID, "instance_member_role", userID, "instance_role", "IAM_OWNER")
+	case org.AggregateType:
+		createTestField(t, tx, orgID, aggregateType, orgID, "org_member_role", userID, "org_role", "ORG_OWNER")
+	case project.AggregateType:
+		createTestField(t, tx, orgID, aggregateType, orgID, "project_member_role", userID, "project_role", "PROJECT_OWNER")
+	default:
+		panic("unknown aggregate type " + aggregateType)
+	}
+	require.NoError(t, err)
+}
+
+func createTestField(t *testing.T, tx pgx.Tx, resourceOwner string, aggregateType eventstore.AggregateType, aggregateID, objectType, objectID, fieldName string, value any) {
+	const query = `INSERT INTO eventstore.fields(
+		instance_id, resource_owner, aggregate_type, aggregate_id, object_type, object_id, field_name, value, value_must_be_unique, should_index, object_revision)
+		VALUES ($1, $2, $3, $4, $5, $6, $7, $8, false, true, 1);`
+	encValue, err := json.Marshal(value)
+	require.NoError(t, err)
+	_, err = tx.Exec(CTX, query, instanceID, resourceOwner, aggregateType, aggregateID, objectType, objectID, fieldName, encValue)
+	require.NoError(t, err)
+
+}

cmd/setup/integration_test/setup_test.go

@@ -0,0 +1,41 @@
+// Package setup_test implements tests for procedural PostgreSQL functions,
+// created in the database during Zitadel setup.
+// Tests depend on `zitadel setup` being run first and therefore is run as integration tests.
+// A PGX connection is used directly to the integration test database.
+// This package assumes the database server available as per integration test defaults.
+// See the [ConnString] constant.
+
+//go:build integration
+
+package setup_test
+
+import (
+	"context"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+const ConnString = "host=localhost port=5432 user=zitadel dbname=zitadel sslmode=disable"
+
+var (
+	CTX    context.Context
+	dbPool *pgxpool.Pool
+)
+
+func TestMain(m *testing.M) {
+	var cancel context.CancelFunc
+	CTX, cancel = context.WithTimeout(context.Background(), time.Second*10)
+
+	var err error
+	dbPool, err = pgxpool.New(context.Background(), ConnString)
+	if err != nil {
+		panic(err)
+	}
+	exit := m.Run()
+	cancel()
+	dbPool.Close()
+	os.Exit(exit)
+}