@nu-art/permissions-backend 0.500.0 → 0.500.6

package/modules/ModuleBE_Permissions.js

@@ -1,458 +1,511 @@
-var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
-    var useValue = arguments.length > 2;
-    for (var i = 0; i < initializers.length; i++) {
-        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
-    }
-    return useValue ? value : void 0;
-};
-var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
-    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
-    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
-    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
-    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
-    var _, done = false;
-    for (var i = decorators.length - 1; i >= 0; i--) {
-        var context = {};
-        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
-        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
-        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
-        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
-        if (kind === "accessor") {
-            if (result === void 0) continue;
-            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
-            if (_ = accept(result.get)) descriptor.get = _;
-            if (_ = accept(result.set)) descriptor.set = _;
-            if (_ = accept(result.init)) initializers.unshift(_);
-        }
-        else if (_ = accept(result)) {
-            if (kind === "field") initializers.unshift(_);
-            else descriptor[key] = _;
-        }
-    }
-    if (target) Object.defineProperty(target, contextIn.name, descriptor);
-    done = true;
-};
-import { _keys, arrayToMap, Dispatcher, filterInstances, flatArray, md5, Module, MUSTNeverHappenException, reduceToMap, } from '@nu-art/ts-common';
-import { ApiHandler, MemKey_ServerApi } from '@nu-art/http-server';
-import { RuntimeBE_Modules } from '@nu-art/db-api-backend';
-import { ApiDef_Permissions, DefaultAccessLevel_Admin, DefaultAccessLevel_Delete, DefaultAccessLevel_NoAccess, DefaultAccessLevel_Read, DefaultAccessLevel_Write, defaultLevelsRouteLookupWords, DuplicateDefaultAccessLevels, toPermissionDomainId, toPermissionGroupId, toPermissionProjectId, trimStartingForwardSlash, } from '@nu-art/permissions-shared';
-import { MemKey_AccountId, ModuleBE_SessionDB } from '@nu-art/user-account-backend';
-import { getRegisteredFunctionPermissions } from '../core/function-permission-registry.js';
-import { Domain_AccountManagement, Domain_Developer, Domain_PermissionsAssign, Domain_PermissionsDefine, PermissionsPackage_Developer, PermissionsPackage_Permissions } from '../permissions.js';
-import { ModuleBE_PermissionsAssert } from './ModuleBE_PermissionsAssert.js';
-import { getCreatePermissionKeyDefaults, getEnvConfigRef } from '../permissions-wire.js';
-import { ModuleBE_PermissionAccessLevelDB, ModuleBE_PermissionAPIDB, ModuleBE_PermissionDomainDB, ModuleBE_PermissionGroupDB, ModuleBE_PermissionProjectDB, ModuleBE_PermissionUserDB } from '../_entity.js';
-const dispatcher_collectPermissionsProjects = new Dispatcher('__collectPermissionsProjects');
-const GroupId_SuperAdmin = '8b54efda69b385a566735cca7be031d5';
-export const PermissionGroup_Permissions_SuperAdmin = {
-    _id: toPermissionGroupId(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: toPermissionGroupId('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: toPermissionGroupId('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: toPermissionGroupId('6bb5feb12d0712ecee77f7f44188ec79'),
-    name: 'Accounts Manager',
-    uiLabel: 'Accounts Manager',
-    accessLevels: {
-        [Domain_AccountManagement.namespace]: DefaultAccessLevel_Write.name,
-    }
-};
-export const PermissionGroup_Account_Admin = {
-    _id: toPermissionGroupId('761a84bdde3f9be3fde9c50402a60401'),
-    name: 'Accounts Admin',
-    uiLabel: 'Accounts Admin',
-    accessLevels: {
-        [Domain_AccountManagement.namespace]: DefaultAccessLevel_Admin.name,
-    }
-};
-export const PermissionGroup_Account_Viewer = {
-    _id: toPermissionGroupId('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: toPermissionProjectId('f60db83936835e0be33e89caa365f0c3'),
-    name: 'Permissions',
-    packages: [PermissionsPackage_Permissions, PermissionsPackage_Developer],
-    groups: PermissionGroups_Permissions
-};
-let ModuleBE_Permissions_Class = (() => {
-    let _classSuper = Module;
-    let _instanceExtraInitializers = [];
-    let _toggleStrictMode_decorators;
-    let _createProject_decorators;
-    return class ModuleBE_Permissions_Class extends _classSuper {
-        static {
-            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
-            _toggleStrictMode_decorators = [ApiHandler(ApiDef_Permissions.toggleStrictMode)];
-            _createProject_decorators = [ApiHandler(ApiDef_Permissions.createProject)];
-            __esDecorate(this, null, _toggleStrictMode_decorators, { kind: "method", name: "toggleStrictMode", static: false, private: false, access: { has: obj => "toggleStrictMode" in obj, get: obj => obj.toggleStrictMode }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _createProject_decorators, { kind: "method", name: "createProject", static: false, private: false, access: { has: obj => "createProject" in obj, get: obj => obj.createProject }, metadata: _metadata }, null, _instanceExtraInitializers);
-            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
-        }
-        init() {
-            super.init();
-        }
-        async toggleStrictMode(_params) {
-            const envConfigRef = getEnvConfigRef(ModuleBE_PermissionsAssert);
-            if (!envConfigRef)
-                return;
-            MemKey_ServerApi.get().addPostCallAction(async () => {
-                const currentConfig = await envConfigRef.get({});
-                currentConfig.strictMode = !currentConfig.strictMode;
-                await envConfigRef.set(currentConfig);
-            });
-        }
-        async createProject(_params) {
-            await this.__performProjectSetup().processor();
-        }
-        // __collectPermissionsProjects() {
-        // 	return PermissionProject_Permissions;
-        // }
-        async __collectSessionData(data) {
-            const permissionUserId = data.accountId;
-            const permissionUser = await ModuleBE_PermissionUserDB.query.uniqueAssert(permissionUserId);
-            const userGroups = filterInstances(await ModuleBE_PermissionGroupDB.query.all(permissionUser.groups.map(g => g.groupId)));
-            const permissionMap = await this.getUserPermissionMap(userGroups);
-            return {
-                key: 'permissions', value: {
-                    domainToValueMap: permissionMap,
-                    roles: userGroups.map(group => ({ key: group.label, uiLabel: group.uiLabel })),
+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 {
+    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,
                 }
-            };
-        }
-        getUserPermissionMap = (__runInitializers(this, _instanceExtraInitializers), 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.
-            });
-            return permissionMap;
+            }
         });
-        __performProjectSetup() {
+    }
+    permissionsAccessResolver = (item) => {
+        if (item._id === BootstrapSAGroupId)
             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 domains/levels from function-permission registry (decorator-collected)
-                    if (projects.length > 0)
-                        await this.createDomainsAndLevelsFromFunctionPermissionRegistry(projects[0]._id);
-                    // Create all AppConfigs
-                    await this.createPermissionsKeys(projects);
-                    //Assign Super Admin if necessary
-                    await this.assignSuperAdmin();
+                __access: {
+                    readers: [BootstrapSAGroupId],
+                    writers: [BootstrapSAGroupId],
+                    deleters: [],
+                    owners: [],
                 }
             };
-        }
-        /**
-         * Creates domains and access levels from the function-permission registry (populated by @RequirePermission decorators).
-         * New (scopeKey, value) pairs get domains/levels created; not assigned to anyone until explicitly assigned.
-         */
-        async createDomainsAndLevelsFromFunctionPermissionRegistry(projectId) {
-            const defs = getRegisteredFunctionPermissions();
-            if (defs.length === 0)
-                return;
-            this.logInfoBold('Creating domains/levels from function-permission registry');
-            const _auditorId = MemKey_AccountId.get();
-            const uniqueScopeKeys = [...new Set(defs.map(d => d.scopeKey))];
-            const domainIdByScopeKey = {};
-            for (const scopeKey of uniqueScopeKeys) {
-                const domainId = toPermissionDomainId(md5(`function-permission-domain/${scopeKey}`));
-                domainIdByScopeKey[scopeKey] = domainId;
-                await ModuleBE_PermissionDomainDB.set.all([{
-                        _id: domainId,
-                        namespace: scopeKey,
-                        projectId,
-                        _auditorId
-                    }]);
-            }
-            const levelValueByName = {
-                'No-Access': DefaultAccessLevel_NoAccess.value,
-                'Read': DefaultAccessLevel_Read.value,
-                'Write': DefaultAccessLevel_Write.value,
-                'Delete': DefaultAccessLevel_Delete.value,
-                'Admin': DefaultAccessLevel_Admin.value
-            };
-            for (const def of defs) {
-                const domainId = domainIdByScopeKey[def.scopeKey];
-                const levelValue = levelValueByName[def.value] ?? 100;
-                const levelId = md5(`${domainId}/${def.value}`);
-                await ModuleBE_PermissionAccessLevelDB.set.all([{
-                        _id: levelId,
-                        domainId,
-                        name: def.value,
-                        value: levelValue,
-                        uiLabel: def.value,
-                        _auditorId
-                    }]);
-                def.domainId = domainId;
-                def.levelId = levelId;
-                def.levelValue = levelValue;
+        return {
+            __access: {
+                readers: [GroupId_PermissionsAdmin],
+                writers: [GroupId_PermissionsAdmin],
+                deleters: [],
+                owners: [],
             }
-            this.logInfoBold(`Created ${uniqueScopeKeys.length} domains and ${defs.length} access levels from function-permission registry`);
-        }
-        ;
-        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);
+        };
+    };
+    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();
+    }
+    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));
         }
-        /**
-         * 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;
+    }
+    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');
+        });
+    }
+    // --- 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]);
+        });
+    }
+    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 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: [],
+        });
+        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;
         }
-        /**
-         * 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;
+        const hasRealMembers = adminGroup.members.some(m => m !== BootstrapSAGroupId);
+        if (hasRealMembers) {
+            this.logDebug(`[FIRST_USER] promoteIfNoAdmin: admin already has non-SA members — returning`);
+            return;
         }
-        /**
-         * 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 ?? 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;
-            });
-            this.logInfoBold(`Created ${dbLevels.length} Access Levels`);
-            return domainNameToLevelNameToDBAccessLevel;
+        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;
         }
-        /**
-         * 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 => {
-                    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;
-                        })
-                    };
-                });
+        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 {
+                    _id: stringToUniqueId(pg._id),
+                    scopeEntries,
+                    accessIds,
+                };
             }));
-            const dbGroups = await ModuleBE_PermissionGroupDB.set.all(groupsToUpsert);
-            this.logInfoBold(`Created ${dbGroups.length} Groups`);
+            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);
         }
-        /**
-         * Creates All the DB_PermissionApi (path-based).
-         * @deprecated API collection deprecated; use function-based permissions and @RequirePermission. Domains/levels from function-permission registry instead.
-         * @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 = RuntimeBE_Modules();
-                    const apiModulesMap = arrayToMap(apiModules, m => m.dbModule.dbDef.dbKey);
-                    this.logDebug(_keys(apiModulesMap));
-                    const crudEndpoints = ['query', 'queryUnique', 'upsert', 'upsertAll', 'deleteUnique', 'deleteQuery', 'deleteAll'];
-                    const _apis = (domain.dbNames || []).map(dbName => {
-                        const apiModule = apiModulesMap[dbName];
-                        if (!apiModule)
-                            throw new MUSTNeverHappenException(`Could not find api module with dbName: ${dbName}`);
-                        const def = apiModule.crudApiDef;
-                        return filterInstances(crudEndpoints.map(key => {
-                            const endpoint = def[key];
-                            if (!endpoint?.path)
-                                return undefined;
-                            const accessLevelNameToAssign = defaultLevelsRouteLookupWords[endpoint.path.substring(endpoint.path.lastIndexOf('/') + 1)];
-                            const accessLevel = domainNameToLevelNameToDBAccessLevel[domain._id][accessLevelNameToAssign];
-                            if (!accessLevel)
-                                return undefined;
-                            return {
-                                projectId: project._id,
-                                path: endpoint.path,
-                                _auditorId,
-                                accessLevelIds: [accessLevel._id]
-                            };
-                        }));
-                    });
-                    apis.push(...flatArray(_apis));
-                    return apis;
-                }));
-            }));
-            const dbApis = await ModuleBE_PermissionAPIDB.set.all(apisToUpsert);
-            this.logInfoBold(`Created ${dbApis.length} APIs`);
+        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);
         }
-        /**
-         * Creates permission keys associated with the given projects.
-         *
-         * @param projects - An array of projects.
-         */
-        async createPermissionsKeys(_projects) {
-            this.logInfoBold('Creating App Config');
-            const createDefaults = getCreatePermissionKeyDefaults();
-            if (createDefaults) {
-                try {
-                    await createDefaults(this);
-                    this.logInfoBold('Created Permission Key defaults.');
-                }
-                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 superAdminGroupId = toPermissionGroupId(GroupId_SuperAdmin);
-            const existingSuperAdmin = (await ModuleBE_PermissionUserDB.query.custom({
-                where: { __groupIds: { $ac: superAdminGroupId } },
-                limit: 1
-            }))[0];
-            if (existingSuperAdmin)
-                return;
-            const accountId = MemKey_AccountId.get();
-            const currentUser = await ModuleBE_PermissionUserDB.query.uniqueAssert(accountId);
-            (currentUser.groups || (currentUser.groups = [])).push({ groupId: superAdminGroupId });
-            await ModuleBE_PermissionUserDB.set.item(currentUser);
-            await ModuleBE_SessionDB._session.rotate.reissue.bySession();
-            this.logInfoBold('Assigned SuperAdmin permissions');
+        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;
+        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();