@nu-art/permissions-backend 0.401.9 → 0.500.6

package/modules/ModuleBE_Permissions.js

@@ -1,357 +1,511 @@
-import { _keys, arrayToMap, Dispatcher, filterInstances, flatArray, Module, MUSTNeverHappenException, reduceToMap, RuntimeModules, } from '@nu-art/ts-common';
-import { addRoutes, createQueryServerApi, MemKey_ServerApi, ModuleBE_AppConfigDB, Storm } from '@nu-art/thunderstorm-backend';
-import { ApiDef_Permissions, DefaultAccessLevel_Admin, DefaultAccessLevel_NoAccess, DefaultAccessLevel_Read, DefaultAccessLevel_Write, defaultLevelsRouteLookupWords, DuplicateDefaultAccessLevels, } from '@nu-art/permissions-shared';
-import { MemKey_AccountId, ModuleBE_SessionDB } from '@nu-art/user-account-backend';
-import { Domain_AccountManagement, Domain_Developer, Domain_PermissionsAssign, Domain_PermissionsDefine, PermissionsPackage_Developer, PermissionsPackage_Permissions } from '../permissions.js';
-import { ModuleBE_PermissionsAssert } from './ModuleBE_PermissionsAssert.js';
-import { ModuleBE_PermissionAccessLevelDB, ModuleBE_PermissionAPIDB, ModuleBE_PermissionDomainDB, ModuleBE_PermissionGroupDB, ModuleBE_PermissionProjectDB, ModuleBE_PermissionUserDB } from '../_entity.js';
-import { trimStartingForwardSlash } from '@nu-art/thunderstorm-shared/route-tools';
-const dispatcher_collectPermissionsProjects = new Dispatcher('__collectPermissionsProjects');
-const GroupId_SuperAdmin = '8b54efda69b385a566735cca7be031d5';
-export const PermissionGroup_Permissions_SuperAdmin = {
-    _id: GroupId_SuperAdmin,
-    name: 'Super Admin',
-    uiLabel: 'Super Admin',
-    accessLevels: {
-        [Domain_PermissionsDefine.namespace]: DefaultAccessLevel_Admin.name,
-        [Domain_PermissionsAssign.namespace]: DefaultAccessLevel_Admin.name,
-        [Domain_AccountManagement.namespace]: DefaultAccessLevel_Admin.name,
-        [Domain_Developer.namespace]: DefaultAccessLevel_Admin.name,
-    }
-};
-export const PermissionGroup_Permissions_Viewer = {
-    _id: '8c38d3bd2d76bbc37b5281f481c0bc1b',
-    name: 'Permissions Viewer',
-    uiLabel: 'Permissions Viewer',
-    accessLevels: {
-        [Domain_AccountManagement.namespace]: DefaultAccessLevel_Read.name,
-        [Domain_PermissionsDefine.namespace]: DefaultAccessLevel_Read.name,
-        [Domain_PermissionsAssign.namespace]: DefaultAccessLevel_Read.name,
-    }
-};
-export const PermissionGroup_Permissions_Editor = {
-    _id: '1524909cae174d0052b76a469b339218',
-    name: 'Permissions Editor',
-    uiLabel: 'Permissions Editor',
-    accessLevels: {
-        [Domain_AccountManagement.namespace]: DefaultAccessLevel_Read.name,
-        [Domain_PermissionsDefine.namespace]: DefaultAccessLevel_Read.name,
-        [Domain_PermissionsAssign.namespace]: DefaultAccessLevel_Write.name,
-    }
-};
-export const PermissionGroup_Account_Manager = {
-    _id: '6bb5feb12d0712ecee77f7f44188ec79',
-    name: 'Accounts Manager',
-    uiLabel: 'Accounts Manager',
-    accessLevels: {
-        [Domain_AccountManagement.namespace]: DefaultAccessLevel_Write.name,
-    }
-};
-export const PermissionGroup_Account_Admin = {
-    _id: '761a84bdde3f9be3fde9c50402a60401',
-    name: 'Accounts Admin',
-    uiLabel: 'Accounts Admin',
-    accessLevels: {
-        [Domain_AccountManagement.namespace]: DefaultAccessLevel_Admin.name,
-    }
-};
-export const PermissionGroup_Account_Viewer = {
-    _id: '7343853a980149ec94f967ac7ff4ccc3',
-    name: 'Accounts Viewer',
-    uiLabel: 'Accounts Viewer',
-    accessLevels: {
-        [Domain_AccountManagement.namespace]: DefaultAccessLevel_Read.name,
-    }
-};
-export const PermissionGroups_Permissions = [
-    PermissionGroup_Permissions_SuperAdmin,
-    PermissionGroup_Permissions_Viewer,
-    PermissionGroup_Permissions_Editor,
-    PermissionGroup_Account_Manager,
-    PermissionGroup_Account_Admin,
-    PermissionGroup_Account_Viewer,
-    // {
-    // 	_id: '60a417683e4016f4d933fee88953f0d5',
-    // 	name: 'Permissions Read Self',
-    // 	accessLevels: {
-    // 		[Domain_PermissionsDefine.namespace]: PermissionsAccessLevel_ReadSelf.name,
-    // 		[Domain_PermissionsAssign.namespace]: PermissionsAccessLevel_ReadSelf.name,
-    // 	}
-    // },
-];
-export const PermissionProject_Permissions = {
-    _id: 'f60db83936835e0be33e89caa365f0c3',
-    name: 'Permissions',
-    packages: [PermissionsPackage_Permissions, PermissionsPackage_Developer],
-    groups: PermissionGroups_Permissions
-};
+import { _keys, ApiException, batchActionParallel, Dispatcher, filterDuplicates, filterInstances, flatArray, Module } from '@nu-art/ts-common';
+import { MemStorage } from '@nu-art/ts-common/mem-storage/MemStorage';
+import { hashToUniqueId, stringToUniqueId } from '@nu-art/db-api-shared';
+import { RuntimeBE_ModulesDB } from '@nu-art/db-api-backend';
+import { AccessScope_Self, AllDocumentAccessKeys, getAllRegisteredScopes, getRegisteredGroupDefinitions, permissionScopeId } from '@nu-art/permissions-shared';
+import { asSetupTaskKey } from '@nu-art/action-processor-backend';
+import { getPermissionScopeValues } from '@nu-art/permissions-shared';
+import { ModuleBE_PermissionScopeDB } from '../_entity/permission-scope/ModuleBE_PermissionScopeDB.js';
+import { ModuleBE_UserPermissionsDB } from '../_entity/user-permissions/ModuleBE_UserPermissionsDB.js';
+import { ModuleBE_AccessGroupDB } from '../_entity/access-group/ModuleBE_AccessGroupDB.js';
+import { ModuleBE_Firebase } from '@nu-art/firebase-backend';
+import { MemKey_ServiceAccountId, MemKey_UserAccessIds, MemKey_UserScopePermissions } from '../consts.js';
+import { wireDocumentAccess } from '../document-access-enforcement.js';
+import { ModuleBE_AccountDB } from '@nu-art/user-account-backend';
+export const ServiceAccountId_Bootstrap = 'bootstrap-admin';
+// --- Well-known group IDs ---
+export const GroupId_AppDefault = hashToUniqueId('group/default');
+export const GroupId_PermissionsAdmin = hashToUniqueId('group/permissions-admin');
+const BootstrapSAGroupId = hashToUniqueId(ServiceAccountId_Bootstrap);
+export const PermissionsInfraGroupIds = AllDocumentAccessKeys.reduce((ids, key) => {
+    ids[key] = hashToUniqueId(`permissions-infra:${key}`);
+    return ids;
+}, {});
+// --- Module ---
+const dispatcher_resolveAdditionalGroupMemberships = new Dispatcher('__resolveAdditionalGroupMemberships');
+export const SetupTaskKey_PermissionsGroups = asSetupTaskKey('permissions-groups');
 class ModuleBE_Permissions_Class extends Module {
-    init() {
-        super.init();
-        addRoutes([
-            createQueryServerApi(ApiDef_Permissions.v1.toggleStrictMode, this.toggleStrictMode),
-            createQueryServerApi(ApiDef_Permissions.v1.createProject, this.__performProjectSetup().processor),
-            // createBodyServerApi(ApiDef_Permissions.v1.connectDomainToRoutes, this.connectDomainToRoutes)
-        ]);
-    }
-    // __collectPermissionsProjects() {
-    // 	return PermissionProject_Permissions;
-    // }
-    async __collectSessionData(data) {
-        const permissionUser = await ModuleBE_PermissionUserDB.query.uniqueAssert(data.accountId);
-        const userGroups = filterInstances(await ModuleBE_PermissionGroupDB.query.all(permissionUser.groups.map(g => g.groupId)));
-        const permissionMap = await this.getUserPermissionMap(userGroups);
+    adminGrantFlagRef;
+    accessResolvers = new Map();
+    moduleScopeKeys = new Map();
+    constructor() {
+        super();
+        this.setDefaultConfig({
+            serviceAccounts: {
+                [ServiceAccountId_Bootstrap]: {
+                    scopes: ['permissions-ui:view', 'access-group:create'],
+                    enabled: true,
+                    systemOnly: true,
+                }
+            }
+        });
+    }
+    permissionsAccessResolver = (item) => {
+        if (item._id === BootstrapSAGroupId)
+            return {
+                __access: {
+                    readers: [BootstrapSAGroupId],
+                    writers: [BootstrapSAGroupId],
+                    deleters: [],
+                    owners: [],
+                }
+            };
         return {
-            key: 'permissions', value: {
-                domainToValueMap: permissionMap,
-                roles: userGroups.map(group => ({ key: group.label, uiLabel: group.uiLabel })),
+            __access: {
+                readers: [GroupId_PermissionsAdmin],
+                writers: [GroupId_PermissionsAdmin],
+                deleters: [],
+                owners: [],
             }
         };
+    };
+    init() {
+        super.init();
+        this.adminGrantFlagRef = ModuleBE_Firebase.createModuleStateFirebaseRef(this, 'grantAdminOnLogin');
+        this.setAccessContextResolver(ModuleBE_AccessGroupDB, this.permissionsAccessResolver);
+        this.setAccessContextResolver(ModuleBE_PermissionScopeDB, this.permissionsAccessResolver);
+        this.setAccessContextResolver(ModuleBE_UserPermissionsDB, this.permissionsAccessResolver);
+        this.wireDocumentAccessToAllModules();
     }
-    getUserPermissionMap = async (userGroups) => {
-        const permissionMap = {};
-        const levelMaps = filterInstances(userGroups.map(i => i._levelsMap));
-        levelMaps.forEach(levelMap => {
-            _keys(levelMap).forEach(domainId => {
-                if (!permissionMap[domainId])
-                    permissionMap[domainId] = 0;
-                if (levelMap[domainId] > permissionMap[domainId])
-                    permissionMap[domainId] = levelMap[domainId];
-            });
-        });
-        //All domains that are not defined for the user, are NoAccess by default.
-        const allDomains = await ModuleBE_PermissionDomainDB.query.where({});
-        allDomains.forEach(domain => {
-            if (!permissionMap[domain._id])
-                permissionMap[domain._id] = DefaultAccessLevel_NoAccess.value; //"fill in the gaps" - All domains that are not defined for the user, are NoAccess by default.
+    setAccessContextResolver(dbModule, resolver, scopeKeys) {
+        this.accessResolvers.set(dbModule.dbDef.dbKey, resolver);
+        if (scopeKeys)
+            this.moduleScopeKeys.set(dbModule.dbDef.dbKey, scopeKeys);
+    }
+    wireDocumentAccessToAllModules() {
+        for (const dbModule of RuntimeBE_ModulesDB()) {
+            const dbKey = dbModule.dbDef.dbKey;
+            wireDocumentAccess(dbModule, () => this.accessResolvers.get(dbKey), () => this.moduleScopeKeys.get(dbKey));
+        }
+    }
+    getAdminGrantFlagRef() {
+        return this.adminGrantFlagRef;
+    }
+    // --- Project setup ---
+    __performProjectSetup() {
+        return [{
+                key: SetupTaskKey_PermissionsGroups,
+                dependsOn: [],
+                processor: () => this.ensureDefinedGroups()
+            }];
+    }
+    async ensureDefinedGroups() {
+        await this.runAsServiceAccount(ServiceAccountId_Bootstrap, async () => {
+            this.logDebug('[FIRST_USER] bootstrap: starting ensureDefinedGroups');
+            await this.ensureBootstrapSAAccessGroup();
+            await this.ensureServiceAccountAccessGroups();
+            await this.ensurePermissionsInfraAccessGroups();
+            await this.ensureScopeEntities();
+            await this.ensureDefaultGroup();
+            await this.ensurePermissionsAdminGroup();
+            await this.ensureAppDefinedGroups();
+            await this.syncPersonalGroupsForExistingAccounts();
+            await this.recomputePermissionsForAllUsers();
+            this.logInfoBold('Recomputed UserPermissions for all users');
+            this.logDebug('[FIRST_USER] bootstrap: ensureDefinedGroups complete');
         });
-        return permissionMap;
-    };
-    toggleStrictMode = async () => {
-        MemKey_ServerApi.get().addPostCallAction(async () => {
-            const envConfigRef = Storm.getInstance().getEnvConfigRef(ModuleBE_PermissionsAssert);
-            const currentConfig = await envConfigRef.get({});
-            currentConfig.strictMode = !currentConfig.strictMode;
-            await envConfigRef.set(currentConfig);
+    }
+    // --- Account lifecycle hooks ---
+    async __onUserLogin(account) {
+        await this.runAsServiceAccount(ServiceAccountId_Bootstrap, async () => {
+            await this.ensurePersonalAccessGroup(account);
+            await this.addToDefaultGroup(account);
+            await this.promoteIfNoAdmin(account);
+            await this.checkAdminGrantFlag(account);
+            await this.resolveAdditionalGroupMemberships(account, 'login');
+            await this.recomputePermissionsForUsers([account._id]);
         });
-    };
-    __performProjectSetup() {
-        return {
-            priority: 100,
-            processor: async () => {
-                const projects = dispatcher_collectPermissionsProjects.dispatchModule();
-                projects.reduce((issues, project) => {
-                    return project.packages.reduce((issues, _package) => {
-                        return issues;
-                    }, issues);
-                }, []);
-                // Create All Projects
-                await this.createPermissionProjects(projects);
-                // Create all AppConfigs
-                await this.createPermissionsKeys(projects);
-                //Assign Super Admin if necessary
-                await this.assignSuperAdmin();
+    }
+    async __onAccountDeleted(account) {
+        await this.runAsServiceAccount(ServiceAccountId_Bootstrap, async () => {
+            const personalGroupId = stringToUniqueId(account._id);
+            const personalGroup = await ModuleBE_AccessGroupDB.query.unique(personalGroupId);
+            if (personalGroup)
+                await ModuleBE_AccessGroupDB.delete.unique(personalGroupId);
+            const userPermId = stringToUniqueId(account._id);
+            const userPerm = await ModuleBE_UserPermissionsDB.query.unique(userPermId);
+            if (userPerm)
+                await ModuleBE_UserPermissionsDB.delete.unique(userPermId);
+            const allGroups = await ModuleBE_AccessGroupDB.query.where({});
+            const groupsContainingUser = allGroups.filter(g => g.members.includes(personalGroupId));
+            for (const group of groupsContainingUser) {
+                group.members = group.members.filter(m => m !== personalGroupId);
+                await ModuleBE_AccessGroupDB.set.item(group);
             }
-        };
+        });
     }
-    ;
-    async createPermissionProjects(projects) {
-        const map_nameToDBProject = await this.createProjects(projects);
-        const map_nameToDbDomain = await this.createDomains(projects, map_nameToDBProject);
-        const domainNameToLevelNameToDBAccessLevel = await this.createAccessLevels(projects, map_nameToDbDomain);
-        await this.createGroups(projects, map_nameToDbDomain, domainNameToLevelNameToDBAccessLevel);
-        await this.createApis(projects, domainNameToLevelNameToDBAccessLevel);
-    }
-    /**
-     * Creates All the DB_PermissionProject
-     *
-     * @param projects - predefined permissions projects
-     */
-    async createProjects(projects) {
-        this.logInfoBold('Creating Projects');
-        const _auditorId = MemKey_AccountId.get();
-        const preDBProjects = await ModuleBE_PermissionProjectDB.set.all(projects.map(project => ({
-            _id: project._id,
-            name: project.name,
-            _auditorId
-        })));
-        const projectsMap_nameToDBProject = reduceToMap(preDBProjects, project => project.name, project => project);
-        this.logInfoBold(`Created ${preDBProjects.length} Projects`);
-        return projectsMap_nameToDBProject;
-    }
-    /**
-     * Creates All the DB_PermissionDomains
-     *
-     * @param projects - predefined permissions projects
-     * @param map_nameToDBProject
-     */
-    async createDomains(projects, map_nameToDBProject) {
-        this.logInfoBold('Creating Domains');
-        const _auditorId = MemKey_AccountId.get();
-        const domainsToUpsert = flatArray(projects.map(project => project.packages.map(_package => _package.domains.map(domain => ({
-            _id: domain._id,
-            namespace: domain.namespace,
-            projectId: map_nameToDBProject[project.name]._id,
-            _auditorId
-        })))));
-        const dbDomain = await ModuleBE_PermissionDomainDB.set.all(domainsToUpsert);
-        const domainsMap_nameToDbDomain = reduceToMap(dbDomain, domain => domain.namespace, domain => domain);
-        this.logInfoBold(`Created ${dbDomain.length} Domains`);
-        return domainsMap_nameToDbDomain;
-    }
-    /**
-     * Creates All the DB_PermissionAccessLevel
-     *
-     * @param projects - predefined permissions projects
-     * @param map_nameToDbDomain
-     */
-    async createAccessLevels(projects, map_nameToDbDomain) {
-        this.logInfoBold('Creating Access Levels');
-        const _auditorId = MemKey_AccountId.get();
-        const levelsToUpsert = flatArray(projects.map(project => project.packages.map(_package => _package.domains.map(domain => {
-            let levels = domain.levels;
-            if (!levels)
-                levels = DuplicateDefaultAccessLevels(domain._id);
-            return levels.map(level => {
-                return {
-                    _id: level._id,
-                    domainId: map_nameToDbDomain[domain.namespace]._id,
-                    value: level.value,
-                    name: level.name,
-                    uiLabel: level.name,
-                    _auditorId
-                };
-            });
-        }))));
-        const dbLevels = await ModuleBE_PermissionAccessLevelDB.set.all(levelsToUpsert);
-        const domainNameToLevelNameToDBAccessLevel = reduceToMap(dbLevels, level => level.domainId, (level, index, map) => {
-            const domainLevels = map[level.domainId] || (map[level.domainId] = {});
-            domainLevels[level.name] = level;
-            return domainLevels;
+    async ensurePersonalAccessGroup(account) {
+        const personalGroupId = stringToUniqueId(account._id);
+        const existing = await ModuleBE_AccessGroupDB.query.unique(personalGroupId);
+        this.logDebug(`[FIRST_USER] ensurePersonalAccessGroup: personalGroupId=${personalGroupId}, existing=${!!existing}`);
+        if (existing)
+            return;
+        await ModuleBE_AccessGroupDB.create.item({
+            _id: personalGroupId,
+            type: 'user',
+            key: AccessScope_Self,
+            label: `User (${account.email ?? account._id})`,
+            members: [],
         });
-        this.logInfoBold(`Created ${dbLevels.length} Access Levels`);
-        return domainNameToLevelNameToDBAccessLevel;
-    }
-    /**
-     * Creates All the DB_PermissionGroup
-     *
-     * @param projects - predefined permissions projects
-     * @param map_nameToDbDomain
-     * @param domainNameToLevelNameToDBAccessLevel
-     */
-    async createGroups(projects, map_nameToDbDomain, domainNameToLevelNameToDBAccessLevel) {
-        this.logInfoBold('Creating Groups');
-        const _auditorId = MemKey_AccountId.get();
-        const groupsToUpsert = flatArray(projects.map(project => {
-            const groupsDef = flatArray([...project.packages.map(p => p.groups || []), ...project.groups || []]);
-            return (groupsDef).map(group => {
+        const verify = await ModuleBE_AccessGroupDB.query.unique(personalGroupId);
+        this.logDebug(`[FIRST_USER] ensurePersonalAccessGroup: created, verified=${!!verify}`);
+    }
+    async addToDefaultGroup(account) {
+        const personalGroupId = stringToUniqueId(account._id);
+        const defaultGroup = await ModuleBE_AccessGroupDB.query.unique(GroupId_AppDefault);
+        this.logDebug(`[FIRST_USER] addToDefaultGroup: defaultGroup=${!!defaultGroup}, members=${defaultGroup?.members?.length}`);
+        if (!defaultGroup)
+            return;
+        if (defaultGroup.members.includes(personalGroupId))
+            return;
+        defaultGroup.members.push(personalGroupId);
+        await ModuleBE_AccessGroupDB.set.item(defaultGroup);
+        this.logDebug(`[FIRST_USER] addToDefaultGroup: user added, members now=${defaultGroup.members.length}`);
+    }
+    async promoteIfNoAdmin(account) {
+        const adminGroup = await ModuleBE_AccessGroupDB.query.unique(GroupId_PermissionsAdmin);
+        this.logDebug(`[FIRST_USER] promoteIfNoAdmin: adminGroup=${!!adminGroup}, members=${JSON.stringify(adminGroup?.members)}`);
+        if (!adminGroup) {
+            this.logDebug('[FIRST_USER] promoteIfNoAdmin: NO admin group found — returning');
+            return;
+        }
+        const hasRealMembers = adminGroup.members.some(m => m !== BootstrapSAGroupId);
+        if (hasRealMembers) {
+            this.logDebug(`[FIRST_USER] promoteIfNoAdmin: admin already has non-SA members — returning`);
+            return;
+        }
+        const personalGroupId = stringToUniqueId(account._id);
+        if (adminGroup.members.includes(personalGroupId))
+            return;
+        adminGroup.members.push(personalGroupId);
+        await ModuleBE_AccessGroupDB.set.item(adminGroup);
+        this.logDebug(`[FIRST_USER] promoteIfNoAdmin: promoted ${personalGroupId} to admin`);
+    }
+    async checkAdminGrantFlag(account) {
+        const flagValue = await this.adminGrantFlagRef.get(false);
+        if (!flagValue)
+            return;
+        const personalGroupId = stringToUniqueId(account._id);
+        const adminGroup = await ModuleBE_AccessGroupDB.query.unique(GroupId_PermissionsAdmin);
+        if (!adminGroup)
+            return;
+        if (adminGroup.members.includes(personalGroupId)) {
+            await this.adminGrantFlagRef.set(false);
+            return;
+        }
+        adminGroup.members.push(personalGroupId);
+        await ModuleBE_AccessGroupDB.set.item(adminGroup);
+        await this.adminGrantFlagRef.set(false);
+        this.logInfo(`Granted Permissions Admin to user ${account._id} via RTDB flag (one-shot)`);
+    }
+    async resolveAdditionalGroupMemberships(account, context) {
+        const results = await dispatcher_resolveAdditionalGroupMemberships.dispatchModuleAsync(account._id, context);
+        const additionalGroupIds = filterDuplicates(flatArray(results));
+        if (additionalGroupIds.length === 0)
+            return;
+        const personalGroupId = stringToUniqueId(account._id);
+        const typedGroupIds = additionalGroupIds.map(id => stringToUniqueId(id));
+        const groups = filterInstances(await ModuleBE_AccessGroupDB.query.all(typedGroupIds));
+        const modifiedGroups = groups.filter(group => !group.members.includes(personalGroupId));
+        if (modifiedGroups.length === 0)
+            return;
+        modifiedGroups.forEach(group => group.members.push(personalGroupId));
+        await ModuleBE_AccessGroupDB.set.all(modifiedGroups);
+        modifiedGroups.forEach(group => this.logInfo(`Added user ${account._id} to group '${group.label}'`));
+    }
+    // --- Permission recomputation (materialized DB_UserPermissions) ---
+    async recomputePermissionsForUsers(accountIds) {
+        if (!accountIds.length)
+            return;
+        const allGroups = await ModuleBE_AccessGroupDB.query.where({});
+        this.logDebug(`[FIRST_USER] recomputePermissionsForUsers: accountIds=${JSON.stringify(accountIds)}, allGroups=${allGroups.length}`);
+        const entitiesToUpsert = await Promise.all(accountIds.map(async (accountId) => {
+            const personalGroupId = stringToUniqueId(accountId);
+            const { scopeEntries, accessIds } = await this.materializeFromGroups(personalGroupId, allGroups);
+            this.logDebug(`[FIRST_USER] materialized for ${accountId}: scopes=${scopeEntries.length}, accessIds=${JSON.stringify(accessIds)}`);
+            return {
+                _id: stringToUniqueId(accountId),
+                scopeEntries,
+                accessIds,
+            };
+        }));
+        if (entitiesToUpsert.length > 0)
+            await ModuleBE_UserPermissionsDB.set.all(entitiesToUpsert);
+    }
+    async recomputePermissionsForAllUsers() {
+        const allGroups = await ModuleBE_AccessGroupDB.query.where({});
+        const userGroups = allGroups.filter(g => g.type === 'user');
+        if (!userGroups.length)
+            return;
+        await batchActionParallel(userGroups, 50, async (batch) => {
+            const entitiesToUpsert = await Promise.all(batch.map(async (pg) => {
+                const { scopeEntries, accessIds } = await this.materializeFromGroups(pg._id, allGroups);
                 return {
-                    projectId: project._id,
-                    _id: group._id,
-                    _auditorId,
-                    label: group.name,
-                    uiLabel: group.name,
-                    accessLevelIds: _keys(group.accessLevels)
-                        .map(key => {
-                        const domainsMapNameToDbDomainElement = map_nameToDbDomain[key];
-                        if (!domainsMapNameToDbDomainElement)
-                            throw new MUSTNeverHappenException(`bah for key ${key}`);
-                        return domainNameToLevelNameToDBAccessLevel[domainsMapNameToDbDomainElement._id][group.accessLevels[key]]._id;
-                    })
+                    _id: stringToUniqueId(pg._id),
+                    scopeEntries,
+                    accessIds,
                 };
-            });
-        }));
-        const dbGroups = await ModuleBE_PermissionGroupDB.set.all(groupsToUpsert);
-        this.logInfoBold(`Created ${dbGroups.length} Groups`);
-    }
-    /**
-     * Creates All the DB_PermissionApi
-     *
-     * @param projects - predefined permissions projects
-     * @param domainNameToLevelNameToDBAccessLevel
-     */
-    async createApis(projects, domainNameToLevelNameToDBAccessLevel) {
-        this.logInfoBold('Creating APIs');
-        const _auditorId = MemKey_AccountId.get();
-        const apisToUpsert = flatArray(projects.map(project => {
-            return project.packages.map(_package => _package.domains.map(domain => {
-                const apis = [];
-                apis.push(...(domain.customApis || []).map(api => ({
-                    projectId: project._id,
-                    path: trimStartingForwardSlash(api.path),
-                    _auditorId,
-                    accessLevelIds: [domainNameToLevelNameToDBAccessLevel[api.domainId ?? domain._id][api.accessLevel]._id]
-                })));
-                const apiModules = arrayToMap(RuntimeModules()
-                    .filter((module) => !!module.apiDef && !!module.dbModule?.dbDef?.dbKey), item => item.dbModule.dbDef.dbKey);
-                this.logDebug(_keys(apiModules));
-                // / I think there is a bug here... comment it and see what happens
-                const _apis = (domain.dbNames || []).map(dbName => {
-                    const apiModule = apiModules[dbName];
-                    if (!apiModule)
-                        throw new MUSTNeverHappenException(`Could not find api module with dbName: ${dbName}`);
-                    const _apiDefs = apiModule.apiDef;
-                    return _keys(_apiDefs).map(_apiDefKey => {
-                        const apiDefs = _apiDefs[_apiDefKey];
-                        return filterInstances(_keys(apiDefs).map(apiDefKey => {
-                            const apiDef = apiDefs[apiDefKey];
-                            const accessLevelNameToAssign = defaultLevelsRouteLookupWords[apiDef.path.substring(apiDef.path.lastIndexOf('/') + 1)];
-                            const accessLevel = domainNameToLevelNameToDBAccessLevel[domain._id][accessLevelNameToAssign];
-                            if (!accessLevel)
-                                return;
-                            const accessId = accessLevel._id;
-                            return {
-                                projectId: project._id,
-                                path: apiDef.path,
-                                _auditorId,
-                                accessLevelIds: [accessId]
-                            };
-                        }));
-                    });
-                });
-                apis.push(...flatArray(_apis));
-                return apis;
             }));
-        }));
-        const dbApis = await ModuleBE_PermissionAPIDB.set.all(apisToUpsert);
-        this.logInfoBold(`Created ${dbApis.length} APIs`);
-    }
-    /**
-     * Creates permission keys associated with the given projects.
-     *
-     * @param projects - An array of projects.
-     */
-    async createPermissionsKeys(projects) {
-        this.logInfoBold('Creating App Config');
-        // const permissionKeysToCreate: PermissionKey_BE<any>[] = filterInstances(flatArray(projects.map(project => project.packages.map(_package => _package.domains.map(domain => domain.permissionKeys)))));
-        try {
-            await ModuleBE_AppConfigDB.createDefaults(this);
-            this.logInfoBold('Created Permission Key defaults.');
+            await ModuleBE_UserPermissionsDB.set.all(entitiesToUpsert);
+        });
+    }
+    async materializeFromGroups(personalGroupId, allGroups) {
+        const personalGroup = allGroups.find(g => g._id === personalGroupId);
+        const accessIds = {
+            [AccessScope_Self]: [personalGroupId],
+        };
+        if (!personalGroup)
+            return { scopeEntries: [], accessIds };
+        const reachableGroups = this.walkGroupGraphUp(personalGroupId, allGroups);
+        const allScopeIds = [];
+        if (personalGroup.scopeEntries?.length)
+            allScopeIds.push(...personalGroup.scopeEntries);
+        for (const group of reachableGroups) {
+            if (!accessIds[group.key])
+                accessIds[group.key] = [];
+            accessIds[group.key] = filterDuplicates([...accessIds[group.key], group._id]);
+            if (group.scopeEntries?.length)
+                allScopeIds.push(...group.scopeEntries);
+        }
+        const dedupedScopeIds = filterDuplicates(allScopeIds);
+        const scopeEntries = dedupedScopeIds.length > 0
+            ? await this.resolveScopeIdsToStrings(dedupedScopeIds)
+            : [];
+        return { scopeEntries, accessIds };
+    }
+    // --- Access group change handler ---
+    async __onAccessGroupChanged(changedGroupIds) {
+        await this.rematerializeForGroups(changedGroupIds);
+    }
+    async rematerializeForGroups(changedGroupIds) {
+        const allGroups = await ModuleBE_AccessGroupDB.query.where({});
+        const userGroups = allGroups.filter(g => g.type === 'user');
+        const affectedAccountIds = [];
+        for (const personalGroup of userGroups) {
+            const reachable = this.walkGroupGraphUp(personalGroup._id, allGroups);
+            const isAffected = reachable.some(g => changedGroupIds.includes(g._id));
+            if (isAffected)
+                affectedAccountIds.push(personalGroup._id);
         }
-        catch (e) {
-            this.logErrorBold('Failed creating Permission Key defaults.', e);
+        if (affectedAccountIds.length > 0)
+            await this.recomputePermissionsForUsers(affectedAccountIds);
+    }
+    walkGroupGraphUp(startGroupId, allGroups) {
+        const visited = new Set();
+        const queue = [startGroupId];
+        const result = [];
+        while (queue.length > 0) {
+            const currentId = queue.shift();
+            if (visited.has(currentId))
+                continue;
+            visited.add(currentId);
+            const parents = allGroups.filter(g => g.members.includes(currentId));
+            for (const parent of parents) {
+                result.push(parent);
+                queue.push(parent._id);
+            }
         }
-        this.logInfoBold('Created App Config');
-    }
-    /**
-     * If no "Super Admin" user is defined in the system!
-     * The first user to press the create project button will become the "Super Admin" of the system
-     *
-     * If a "Super Admin" already exists in the system, a 403 will be thrown
-     */
-    assignSuperAdmin = async () => {
-        this.logInfoBold('Assigning SuperAdmin permissions');
-        const existingSuperAdmin = (await ModuleBE_PermissionUserDB.query.custom({
-            where: { __groupIds: { $ac: GroupId_SuperAdmin } },
-            limit: 1
-        }))[0];
-        if (existingSuperAdmin)
+        return result;
+    }
+    async resolveScopeIdsToStrings(scopeIds) {
+        const typedScopeIds = scopeIds.map(id => stringToUniqueId(id));
+        const scopeEntities = filterInstances(await ModuleBE_PermissionScopeDB.query.all(typedScopeIds));
+        return this.deduplicateScopeEntries(scopeEntities);
+    }
+    deduplicateScopeEntries(scopeEntities) {
+        const scopeMaxIdx = {};
+        for (const entity of scopeEntities) {
+            const scopeValues = getPermissionScopeValues(entity.key);
+            const valueIdx = scopeValues ? scopeValues.indexOf(entity.value) : -1;
+            const current = scopeMaxIdx[entity.key];
+            if (!current || valueIdx > current.idx)
+                scopeMaxIdx[entity.key] = { value: entity.value, idx: valueIdx };
+        }
+        return _keys(scopeMaxIdx).map(k => `${k}:${scopeMaxIdx[k].value}`);
+    }
+    // --- Service account elevation ---
+    async runAsServiceAccount(saId, action) {
+        const saConfig = this.config.serviceAccounts[saId];
+        if (!saConfig || !saConfig.enabled)
+            throw new ApiException(403, `Service account '${saId}' is not enabled`);
+        if (saConfig.systemOnly) {
+            const store = MemStorage.getStore();
+            if (store && MemKey_UserScopePermissions.peak() !== undefined)
+                throw new ApiException(403, `System-only service account '${saId}' cannot be used within a user context`);
+        }
+        const scopes = saId === ServiceAccountId_Bootstrap
+            ? this.resolveBootstrapScopes()
+            : saConfig.scopes;
+        const personalGroupId = hashToUniqueId(saId);
+        const accessIds = saId === ServiceAccountId_Bootstrap
+            ? this.resolveBootstrapAccessIds()
+            : await this.resolveSAAccessIds(personalGroupId);
+        const memStorage = new MemStorage();
+        return memStorage.init(async () => {
+            MemKey_ServiceAccountId.set(saId);
+            MemKey_UserScopePermissions.set(scopes);
+            MemKey_UserAccessIds.set(accessIds);
+            return action();
+        });
+    }
+    async resolveSAAccessIds(personalGroupId) {
+        return this.runAsServiceAccount(ServiceAccountId_Bootstrap, async () => {
+            const allGroups = await ModuleBE_AccessGroupDB.query.where({});
+            const { accessIds } = await this.materializeFromGroups(personalGroupId, allGroups);
+            return accessIds;
+        });
+    }
+    resolveBootstrapAccessIds() {
+        return {
+            [AccessScope_Self]: [BootstrapSAGroupId],
+            'permissions-admin': [GroupId_PermissionsAdmin],
+        };
+    }
+    resolveBootstrapScopes() {
+        return [
+            'permissions-ui:view',
+            'access-group:create',
+        ];
+    }
+    // --- Bootstrap: ensure service account access group ---
+    async ensureBootstrapSAAccessGroup() {
+        const existing = await ModuleBE_AccessGroupDB.query.unique(BootstrapSAGroupId);
+        if (existing)
             return;
-        const currentUser = await ModuleBE_PermissionUserDB.query.uniqueAssert(MemKey_AccountId.get());
-        (currentUser.groups || (currentUser.groups = [])).push({ groupId: GroupId_SuperAdmin });
-        await ModuleBE_PermissionUserDB.set.item(currentUser);
-        await ModuleBE_SessionDB._session.rotate.reissue.bySession();
-        this.logInfoBold('Assigned SuperAdmin permissions');
-    };
+        await ModuleBE_AccessGroupDB.create.item({
+            _id: BootstrapSAGroupId,
+            type: 'service-account',
+            key: ServiceAccountId_Bootstrap,
+            label: 'Bootstrap Admin (SA)',
+            members: [],
+        });
+        this.logInfoBold('Created bootstrap service account access group');
+    }
+    async ensureServiceAccountAccessGroups() {
+        const saKeys = _keys(this.config.serviceAccounts).filter(saId => saId !== ServiceAccountId_Bootstrap);
+        if (saKeys.length === 0)
+            return;
+        const entries = saKeys.map(saId => ({
+            saId,
+            groupId: hashToUniqueId(saId),
+        }));
+        const existing = filterInstances(await ModuleBE_AccessGroupDB.query.all(entries.map(e => e.groupId)));
+        const existingIds = new Set(existing.map(g => g._id));
+        const toCreate = entries
+            .filter(e => !existingIds.has(e.groupId))
+            .map(e => ({
+            _id: e.groupId,
+            type: 'service-account',
+            key: e.saId,
+            label: `SA: ${e.saId}`,
+            members: [],
+        }));
+        if (toCreate.length === 0)
+            return;
+        await ModuleBE_AccessGroupDB.create.all(toCreate);
+        this.logInfoBold(`Created ${toCreate.length} service account access groups`);
+    }
+    // --- Bootstrap: ensure permissions infrastructure access groups ---
+    async ensurePermissionsInfraAccessGroups() {
+        const entries = AllDocumentAccessKeys.map(accessKey => ({
+            accessKey,
+            groupId: PermissionsInfraGroupIds[accessKey],
+        }));
+        const existing = filterInstances(await ModuleBE_AccessGroupDB.query.all(entries.map(e => e.groupId)));
+        const existingMap = new Map(existing.map(g => [g._id, g]));
+        const items = entries.map(e => {
+            const existingGroup = existingMap.get(e.groupId);
+            const members = filterDuplicates([GroupId_PermissionsAdmin, ...(existingGroup?.members ?? [])]);
+            return {
+                _id: e.groupId,
+                type: 'entity',
+                key: 'permissions',
+                label: `Permissions Infra ${e.accessKey}`,
+                members,
+            };
+        });
+        await ModuleBE_AccessGroupDB.set.all(items);
+        this.logInfoBold('Ensured permissions infrastructure access groups');
+    }
+    // --- Bootstrap: ensure scope entities ---
+    async ensureScopeEntities() {
+        const registeredScopes = getAllRegisteredScopes();
+        this.logDebug(`Registered scopes: ${registeredScopes.length} definitions`);
+        const scopeEntities = registeredScopes.flatMap(scope => scope.values.map(value => ({
+            _id: permissionScopeId(scope.key, value),
+            key: scope.key,
+            value,
+        })));
+        if (scopeEntities.length === 0)
+            return;
+        await ModuleBE_PermissionScopeDB.set.all(scopeEntities);
+        this.logInfoBold(`Ensured ${scopeEntities.length} scope entities`);
+    }
+    // --- Bootstrap: ensure default group ---
+    async ensureDefaultGroup() {
+        const existing = await ModuleBE_AccessGroupDB.query.unique(GroupId_AppDefault);
+        await ModuleBE_AccessGroupDB.set.all([{
+                _id: GroupId_AppDefault,
+                type: 'custom',
+                key: 'default',
+                label: 'Default',
+                members: existing?.members ?? [],
+                scopeEntries: [],
+            }]);
+        this.logInfoBold('Default group ensured');
+    }
+    // --- Bootstrap: permissions admin group ---
+    async ensurePermissionsAdminGroup() {
+        const scopeEntries = [
+            permissionScopeId('permissions-ui', 'view'),
+            permissionScopeId('access-group', 'create'),
+        ];
+        const existingAdmin = await ModuleBE_AccessGroupDB.query.unique(GroupId_PermissionsAdmin);
+        const adminMembers = filterDuplicates([BootstrapSAGroupId, ...(existingAdmin?.members ?? [])]);
+        this.logDebug(`[FIRST_USER] ensurePermissionsAdminGroup: id=${GroupId_PermissionsAdmin}, existing=${!!existingAdmin}, members=${JSON.stringify(adminMembers)}, scopes=${scopeEntries.length}`);
+        await ModuleBE_AccessGroupDB.set.all([{
+                _id: GroupId_PermissionsAdmin,
+                type: 'custom',
+                key: 'permissions-admin',
+                label: 'Permissions Admin',
+                members: adminMembers,
+                scopeEntries,
+            }]);
+        this.logInfoBold('Permissions Admin group upserted');
+    }
+    // --- Bootstrap: app-defined groups ---
+    async ensureAppDefinedGroups() {
+        const groupDefs = getRegisteredGroupDefinitions();
+        if (groupDefs.length === 0)
+            return;
+        const entries = groupDefs.map(def => ({
+            def,
+            groupId: hashToUniqueId(`group/${def.key}`),
+        }));
+        const existing = filterInstances(await ModuleBE_AccessGroupDB.query.all(entries.map(e => e.groupId)));
+        const existingMap = new Map(existing.map(g => [g._id, g]));
+        const items = entries.map(e => {
+            const existingGroup = existingMap.get(e.groupId);
+            const declaredMemberIds = (e.def.memberKeys ?? []).map(key => hashToUniqueId(`group/${key}`));
+            const mergedMembers = filterDuplicates([...declaredMemberIds, ...(existingGroup?.members ?? [])]);
+            return {
+                _id: e.groupId,
+                type: 'custom',
+                key: e.def.scopeKey ?? e.def.key,
+                label: e.def.label,
+                members: mergedMembers,
+                scopeEntries: filterDuplicates(e.def.scopes.map(({ scope, value }) => permissionScopeId(scope.key, value))),
+            };
+        });
+        await ModuleBE_AccessGroupDB.set.all(items);
+        this.logInfoBold(`Ensured ${groupDefs.length} application-defined groups: [${groupDefs.map(d => d.label).join(', ')}]`);
+    }
+    // --- Bootstrap: sync personal groups for existing accounts ---
+    async syncPersonalGroupsForExistingAccounts() {
+        const accounts = await ModuleBE_AccountDB.query.where({});
+        this.logDebug(`Found ${accounts.length} accounts for personal group sync`);
+        for (const account of accounts)
+            await this.ensurePersonalAccessGroup(account);
+    }
 }
 export const ModuleBE_Permissions = new ModuleBE_Permissions_Class();