@adula/kit 0.2.0-alpha.1

package/build/src/core/roles.js

@@ -0,0 +1,319 @@
+import { conditionSql } from '../auth/sql.js';
+import { KitError } from '../admin/errors.js';
+import { logActivity } from './activity.js';
+import { administrationGuard } from './administration_guard.js';
+const RESOURCE = 'core.roles';
+const ACTION_ORDER = ['view', 'create', 'update', 'delete', 'submit', 'cancel', 'amend'];
+export const ALL_SUBJECT_LABEL = { ar: 'كل الكيانات', en: 'All resources' };
+function standardConditionFields(resource) {
+    const field = (key, ar, en) => ({
+        key,
+        label: { ar, en },
+        type: 'integer',
+        conditionable: true,
+    });
+    return [
+        field('id', 'المعرّف', 'ID'),
+        field('createdBy', 'أنشأه', 'Created by'),
+        field('updatedBy', 'عدّله', 'Updated by'),
+        ...(resource.scoped ? [field('orgUnitId', 'الوحدة التنظيمية', 'Organization unit')] : []),
+        ...(resource.submittable ? [field('docStatus', 'حالة المستند', 'Document status')] : []),
+        ...(resource.version ? [field('version', 'الإصدار', 'Version')] : []),
+    ];
+}
+function matrixFields(resource) {
+    return Object.entries(resource.fields).map(([key, field]) => ({
+        key,
+        label: field.label,
+        type: field.type,
+        conditionable: !['hasMany', 'json', 'attachment'].includes(field.type),
+    }));
+}
+function roleName(value) {
+    const name = typeof value === 'string' ? value.trim() : '';
+    if (!name || name.length > 100)
+        throw new KitError(422, 'E_ROLE_NAME', 'اسم الدور مطلوب (حتى 100 حرف)');
+    return name;
+}
+function permissionLevel(value) {
+    const level = Number(value ?? 0);
+    if (!Number.isSafeInteger(level) || level < 0 || level > 9)
+        throw new KitError(422, 'E_ROLE_LEVEL', 'مستوى الصلاحية رقم بين 0 و9');
+    return level;
+}
+function toRule(row) {
+    return {
+        id: Number(row.id),
+        subject: String(row.subject),
+        action: String(row.action),
+        inverted: Boolean(row.inverted),
+        conditions: row.conditions ?? null,
+        fields: row.fields ?? null,
+    };
+}
+export class RolesAdmin {
+    db;
+    registry;
+    constructor(db, registry) {
+        this.db = db;
+        this.registry = registry;
+    }
+    async list() {
+        const rows = await this.db('roles as r')
+            .select('r.id', 'r.name', 'r.permission_level', this.db.raw('(SELECT count(*) FROM role_rules rr WHERE rr.role_id = r.id) AS rules'), this.db.raw('(SELECT count(DISTINCT ur.user_id) FROM user_roles ur WHERE ur.role_id = r.id) AS users'))
+            .orderBy('r.name');
+        return rows.map((row) => ({
+            id: row.id,
+            name: row.name,
+            permissionLevel: row.permission_level,
+            rules: Number(row.rules),
+            users: Number(row.users),
+        }));
+    }
+    async get(id) {
+        const role = await this.find(this.db, id);
+        const rules = await this.db('role_rules')
+            .where('role_id', id)
+            .orderBy(['subject', 'action', 'inverted']);
+        const users = await this.db('user_roles')
+            .where('role_id', id)
+            .countDistinct('user_id as count')
+            .first();
+        return {
+            id: role.id,
+            name: role.name,
+            permissionLevel: role.permission_level,
+            users: Number(users?.count ?? 0),
+            rules: rules.map(toRule),
+        };
+    }
+    async create(actorId, input) {
+        const name = roleName(input.name);
+        const level = permissionLevel(input.permissionLevel);
+        return this.db.transaction(async (trx) => {
+            if (await trx('roles').where('name', name).first())
+                throw new KitError(409, 'E_ROLE_EXISTS', 'يوجد دور بهذا الاسم');
+            const [role] = await trx('roles').insert({ name, permission_level: level }).returning('*');
+            await logActivity(trx, {
+                resource: RESOURCE,
+                recordId: role.id,
+                actorId,
+                action: 'create',
+                changes: { name, permissionLevel: level },
+            });
+            return { id: role.id, name, permissionLevel: level };
+        });
+    }
+    async rename(actorId, id, value) {
+        const name = roleName(value);
+        return this.db.transaction(async (trx) => {
+            const role = await this.find(trx, id);
+            if (role.name === 'administrator' && name !== role.name)
+                throw new KitError(409, 'E_BOOTSTRAP_ROLE', 'اسم دور مدير النظام الأساسي محمي لاستعادة الوصول عند الحاجة');
+            if (await trx('roles').where('name', name).whereNot('id', id).first())
+                throw new KitError(409, 'E_ROLE_EXISTS', 'يوجد دور بهذا الاسم');
+            await trx('roles').where('id', id).update({ name });
+            await logActivity(trx, {
+                resource: RESOURCE,
+                recordId: id,
+                actorId,
+                action: 'rename',
+                changes: { from: role.name, to: name },
+            });
+        });
+    }
+    async setPermissionLevel(actorId, id, value) {
+        const level = permissionLevel(value);
+        return this.db.transaction(async (trx) => {
+            const role = await this.find(trx, id);
+            await trx('roles').where('id', id).update({ permission_level: level });
+            await logActivity(trx, {
+                resource: RESOURCE,
+                recordId: id,
+                actorId,
+                action: 'set_level',
+                changes: { from: role.permission_level, to: level },
+            });
+        });
+    }
+    async delete(actorId, id) {
+        return this.db.transaction(async (trx) => {
+            const role = await this.find(trx, id);
+            const assigned = await trx('user_roles').where('role_id', id).first();
+            if (assigned)
+                throw new KitError(409, 'E_ROLE_IN_USE', 'لا يمكن حذف دور مسند إلى مستخدمين');
+            await trx('roles').where('id', id).delete();
+            await logActivity(trx, {
+                resource: RESOURCE,
+                recordId: id,
+                actorId,
+                action: 'delete',
+                changes: { name: role.name },
+            });
+        });
+    }
+    /** Subjects × actions derived from the registry; the UI never hard-codes resources. */
+    matrix() {
+        const resources = this.registry.all();
+        const union = ACTION_ORDER.filter((action) => resources.some((resource) => resource.actions.includes(action)));
+        return {
+            actions: [...union, 'invite', 'manage'],
+            subjects: [
+                {
+                    name: 'all',
+                    label: ALL_SUBJECT_LABEL,
+                    actions: [...union, 'invite', 'manage'],
+                    fields: [],
+                    conditionFields: [],
+                },
+                {
+                    name: 'core.users',
+                    label: { ar: 'دعوات المستخدمين', en: 'User invitations' },
+                    actions: ['invite', 'manage'],
+                    fields: [],
+                    conditionFields: [],
+                },
+                ...resources.map((resource) => {
+                    const fields = matrixFields(resource);
+                    return {
+                        name: resource.name,
+                        label: resource.label,
+                        actions: [...ACTION_ORDER.filter((a) => resource.actions.includes(a)), 'manage'],
+                        fields,
+                        conditionFields: [
+                            ...standardConditionFields(resource),
+                            ...fields.filter((field) => field.conditionable),
+                        ],
+                    };
+                }),
+            ],
+        };
+    }
+    async setRule(actorId, roleId, input) {
+        const rule = this.validateRule(input);
+        return this.db.transaction(async (trx) => {
+            const verifyAccess = await administrationGuard(trx, actorId);
+            await this.find(trx, roleId);
+            const values = {
+                conditions: rule.conditions ? JSON.stringify(rule.conditions) : null,
+                fields: rule.fields ? JSON.stringify(rule.fields) : null,
+            };
+            const existing = await trx('role_rules')
+                .where({
+                role_id: roleId,
+                subject: rule.subject,
+                action: rule.action,
+                inverted: rule.inverted,
+            })
+                .first();
+            const [row] = existing
+                ? await trx('role_rules').where('id', existing.id).update(values).returning('*')
+                : await trx('role_rules')
+                    .insert({
+                    role_id: roleId,
+                    subject: rule.subject,
+                    action: rule.action,
+                    inverted: rule.inverted,
+                    ...values,
+                })
+                    .returning('*');
+            const saved = toRule(row);
+            await verifyAccess();
+            await logActivity(trx, {
+                resource: RESOURCE,
+                recordId: roleId,
+                actorId,
+                action: 'set_rule',
+                changes: { rule: saved },
+            });
+            return saved;
+        });
+    }
+    async removeRule(actorId, roleId, ruleId) {
+        return this.db.transaction(async (trx) => {
+            const verifyAccess = await administrationGuard(trx, actorId);
+            await this.find(trx, roleId);
+            const [row] = await trx('role_rules')
+                .where({ id: ruleId, role_id: roleId })
+                .delete()
+                .returning('*');
+            if (!row)
+                throw new KitError(404, 'E_RULE_NOT_FOUND', 'القاعدة غير موجودة');
+            await verifyAccess();
+            await logActivity(trx, {
+                resource: RESOURCE,
+                recordId: roleId,
+                actorId,
+                action: 'remove_rule',
+                changes: { rule: toRule(row) },
+            });
+        });
+    }
+    validateRule(input) {
+        const subject = typeof input.subject === 'string' ? input.subject : '';
+        let resource;
+        if (subject !== 'all' && subject !== 'core.users') {
+            try {
+                resource = this.registry.get(subject);
+            }
+            catch {
+                throw new KitError(422, 'E_RULE_SUBJECT', 'الكيان غير معروف');
+            }
+        }
+        const action = typeof input.action === 'string' ? input.action : '';
+        const allowed = subject === 'core.users'
+            ? ['invite', 'manage']
+            : resource
+                ? [...resource.actions, 'manage']
+                : [...new Set(this.registry.all().flatMap((r) => [...r.actions])), 'invite', 'manage'];
+        if (!allowed.includes(action))
+            throw new KitError(422, 'E_RULE_ACTION', 'الإجراء غير متاح لهذا الكيان');
+        const inverted = Boolean(input.inverted);
+        let conditions = null;
+        if (input.conditions !== undefined &&
+            input.conditions !== null &&
+            !(typeof input.conditions === 'object' &&
+                !Array.isArray(input.conditions) &&
+                !Object.keys(input.conditions).length)) {
+            if (!resource)
+                throw new KitError(422, 'E_RULE_CONDITIONS', 'الشروط تتطلب اختيار كيان محدد');
+            if (typeof input.conditions !== 'object' || Array.isArray(input.conditions))
+                throw new KitError(422, 'E_RULE_CONDITIONS', 'الشروط يجب أن تكون كائناً');
+            if ('orgPath' in input.conditions)
+                throw new KitError(422, 'E_RULE_CONDITIONS', 'orgPath محجوز لنطاق الدور');
+            const conditionable = new Set([...standardConditionFields(resource), ...matrixFields(resource)]
+                .filter((field) => field.conditionable)
+                .map((field) => field.key));
+            for (const field of Object.keys(input.conditions))
+                if (!conditionable.has(field))
+                    throw new KitError(422, 'E_RULE_CONDITIONS', `الحقل ${field} لا يقبل الشروط`);
+            try {
+                conditionSql(input.conditions, resource);
+            }
+            catch (error) {
+                throw new KitError(422, 'E_RULE_CONDITIONS', `شرط غير مدعوم: ${error.message}`);
+            }
+            conditions = input.conditions;
+        }
+        let fields = null;
+        if (input.fields !== undefined &&
+            input.fields !== null &&
+            !(Array.isArray(input.fields) && !input.fields.length)) {
+            if (!resource)
+                throw new KitError(422, 'E_RULE_FIELDS', 'قائمة الحقول تتطلب اختيار كيان محدد');
+            if (!Array.isArray(input.fields) || !input.fields.every((f) => typeof f === 'string'))
+                throw new KitError(422, 'E_RULE_FIELDS', 'قائمة الحقول غير صالحة');
+            for (const field of input.fields)
+                if (!(field in resource.fields))
+                    throw new KitError(422, 'E_RULE_FIELDS', `الحقل ${field} غير معروف`);
+            fields = [...new Set(input.fields)];
+        }
+        return { subject, action, inverted, conditions, fields };
+    }
+    async find(db, id) {
+        const role = await db('roles').where('id', id).first();
+        if (!role)
+            throw new KitError(404, 'E_ROLE_NOT_FOUND', 'الدور غير موجود');
+        return role;
+    }
+}

package/build/src/core/saved_views.d.ts

@@ -0,0 +1,37 @@
+import type { Knex } from 'knex';
+import type { ResourceRegistry } from '../resource/registry.js';
+import { type Actor } from '../auth/ability.js';
+export type SavedViewQuery = {
+    search?: string;
+    sort?: string;
+    direction?: 'asc' | 'desc';
+    filters?: Record<string, string | number | boolean | null>;
+};
+export type SavedView = {
+    id: number;
+    name: string;
+    query: SavedViewQuery;
+    shared: boolean;
+    own: boolean;
+};
+/**
+ * A saved view is stored user input that later drives a list query, so every key
+ * is validated against the resource definition before it is written and again
+ * when it is read back: a field that stopped being sortable or filterable must
+ * not resurrect as an unchecked query parameter after an upgrade.
+ */
+export declare class SavedViews {
+    private db;
+    private registry;
+    constructor(db: Knex, registry: ResourceRegistry);
+    list(name: string, actor: Actor): Promise<SavedView[]>;
+    save(name: string, actor: Actor, input: {
+        name: string;
+        query: unknown;
+        shared?: boolean;
+    }): Promise<SavedView>;
+    remove(name: string, actor: Actor, id: number): Promise<void>;
+    private authorize;
+    /** Returns null for a stored view the resource no longer supports; throws on user input. */
+    private sanitize;
+}

package/build/src/core/saved_views.js

@@ -0,0 +1,139 @@
+import { buildAbility } from '../auth/ability.js';
+import { KitError } from '../admin/errors.js';
+const NAME_LIMIT = 60;
+const VIEW_LIMIT = 50;
+/**
+ * A saved view is stored user input that later drives a list query, so every key
+ * is validated against the resource definition before it is written and again
+ * when it is read back: a field that stopped being sortable or filterable must
+ * not resurrect as an unchecked query parameter after an upgrade.
+ */
+export class SavedViews {
+    db;
+    registry;
+    constructor(db, registry) {
+        this.db = db;
+        this.registry = registry;
+    }
+    async list(name, actor) {
+        const resource = this.authorize(name, actor);
+        const rows = await this.db('saved_views')
+            .where('resource', resource.name)
+            .where((where) => where.where('user_id', actor.id).orWhere('shared', true))
+            .orderBy('name')
+            .limit(VIEW_LIMIT * 2);
+        return rows.flatMap((row) => {
+            const query = this.sanitize(resource, row.query);
+            return query
+                ? [
+                    {
+                        id: Number(row.id),
+                        name: String(row.name),
+                        query,
+                        shared: Boolean(row.shared),
+                        own: Number(row.user_id) === actor.id,
+                    },
+                ]
+                : [];
+        });
+    }
+    async save(name, actor, input) {
+        const resource = this.authorize(name, actor);
+        const label = typeof input.name === 'string' ? input.name.trim() : '';
+        if (!label || label.length > NAME_LIMIT)
+            throw new KitError(422, 'E_VIEW_NAME', 'اسم العرض مطلوب ولا يتجاوز 60 حرفاً');
+        const query = this.sanitize(resource, input.query, true);
+        const shared = input.shared === true;
+        const existing = await this.db('saved_views')
+            .where({ user_id: actor.id, resource: resource.name, name: label })
+            .first('id');
+        if (!existing) {
+            const [{ count }] = await this.db('saved_views')
+                .where({ user_id: actor.id, resource: resource.name })
+                .count('* as count');
+            if (Number(count) >= VIEW_LIMIT)
+                throw new KitError(422, 'E_VIEW_LIMIT', 'بلغت الحد الأقصى للعروض المحفوظة لهذا الكيان');
+        }
+        const values = {
+            user_id: actor.id,
+            resource: resource.name,
+            name: label,
+            query: JSON.stringify(query),
+            shared,
+            updated_at: this.db.fn.now(),
+        };
+        const [row] = existing
+            ? await this.db('saved_views').where('id', existing.id).update(values).returning('*')
+            : await this.db('saved_views').insert(values).returning('*');
+        return { id: Number(row.id), name: label, query, shared, own: true };
+    }
+    async remove(name, actor, id) {
+        const resource = this.authorize(name, actor);
+        const removed = await this.db('saved_views')
+            .where({ id, resource: resource.name, user_id: actor.id })
+            .del();
+        if (!removed)
+            throw new KitError(404, 'E_VIEW_NOT_FOUND', 'العرض المحفوظ غير موجود');
+    }
+    authorize(name, actor) {
+        const resource = this.registry.get(name);
+        const ability = buildAbility(actor.rules, this.registry.all());
+        if (!resource.actions.includes('view') || !ability.can('view', resource.name))
+            throw new KitError(403, 'E_FORBIDDEN', 'ليس لديك صلاحية لهذا الكيان');
+        return resource;
+    }
+    /** Returns null for a stored view the resource no longer supports; throws on user input. */
+    sanitize(resource, value, strict = false) {
+        const reject = (code, message) => {
+            if (strict)
+                throw new KitError(422, code, message);
+            return null;
+        };
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return reject('E_VIEW_QUERY', 'تعريف العرض غير صالح');
+        const input = value;
+        for (const key of Object.keys(input))
+            if (!['search', 'sort', 'direction', 'filters'].includes(key))
+                return reject('E_VIEW_QUERY', `مفتاح غير مدعوم في العرض: ${key}`);
+        const query = {};
+        if (input.search !== undefined && input.search !== null && input.search !== '') {
+            if (typeof input.search !== 'string' || input.search.length > 200)
+                return reject('E_VIEW_QUERY', 'نص البحث غير صالح');
+            if (!Object.values(resource.fields).some((field) => field.searchable))
+                return reject('E_VIEW_QUERY', 'هذا الكيان لا يدعم البحث النصي');
+            query.search = input.search;
+        }
+        if (input.sort !== undefined && input.sort !== null && input.sort !== '') {
+            if (typeof input.sort !== 'string' || !resource.fields[input.sort]?.sortable)
+                return reject('E_VIEW_QUERY', 'حقل الفرز غير مدعوم');
+            query.sort = input.sort;
+            if (input.direction !== undefined && input.direction !== null) {
+                if (input.direction !== 'asc' && input.direction !== 'desc')
+                    return reject('E_VIEW_QUERY', 'اتجاه الفرز غير صالح');
+                query.direction = input.direction;
+            }
+        }
+        else if (input.direction !== undefined && input.direction !== null && input.direction !== '')
+            return reject('E_VIEW_QUERY', 'اتجاه الفرز يحتاج حقل فرز');
+        if (input.filters !== undefined && input.filters !== null) {
+            if (typeof input.filters !== 'object' || Array.isArray(input.filters))
+                return reject('E_VIEW_QUERY', 'تصفية العرض غير صالحة');
+            const filters = {};
+            for (const [key, entry] of Object.entries(input.filters)) {
+                if (!resource.fields[key]?.filterable)
+                    return reject('E_VIEW_QUERY', `حقل التصفية غير مدعوم: ${key}`);
+                if (entry === undefined || entry === '')
+                    continue;
+                if (entry !== null &&
+                    typeof entry !== 'string' &&
+                    typeof entry !== 'number' &&
+                    typeof entry !== 'boolean')
+                    return reject('E_VIEW_QUERY', `قيمة التصفية غير صالحة: ${key}`);
+                filters[key] = entry;
+            }
+            if (Object.keys(filters).length)
+                query.filters = filters;
+        }
+        return query;
+    }
+}

package/build/src/core/settings.d.ts

@@ -0,0 +1,29 @@
+import type { Knex } from 'knex';
+import type { JsonValue } from '../resource/types.js';
+export type SettingScope = 'system' | 'org_unit' | 'user';
+export type SettingRow = {
+    id: number;
+    key: string;
+    scope: SettingScope;
+    scopeId: string;
+    value: JsonValue;
+    readOnly: boolean;
+};
+export type SettingInput = {
+    key: string;
+    scope: SettingScope;
+    scopeId?: string;
+    value: unknown;
+};
+export declare const SETTING_SCOPES: SettingScope[];
+export declare const PROTECTED_SETTING_KEYS: string[];
+export declare function isProtectedSetting(key: string): boolean;
+export declare function parseSettingValue(text: string): unknown;
+export declare class SettingsAdmin {
+    private db;
+    constructor(db: Knex);
+    list(scope: SettingScope, scopeId?: string): Promise<SettingRow[]>;
+    upsert(actorId: number, input: SettingInput): Promise<SettingRow>;
+    delete(actorId: number, id: number): Promise<void>;
+    private scopeId;
+}

package/build/src/core/settings.js

@@ -0,0 +1,113 @@
+import { KitError } from '../admin/errors.js';
+import { logActivity } from './activity.js';
+import { UI_PREFERENCES_KEY, validateUiPreferences } from './ui_preferences.js';
+export const SETTING_SCOPES = ['system', 'org_unit', 'user'];
+// Written by install, scheduler, worker and backup verification; never by the settings screen.
+export const PROTECTED_SETTING_KEYS = [
+    'kit.version',
+    'scheduler.heartbeat',
+    'worker.heartbeat',
+    'mail.delivery_test',
+];
+const RESOURCE = 'core.settings';
+export function isProtectedSetting(key) {
+    return (PROTECTED_SETTING_KEYS.includes(key) || key.startsWith('backup.') || key.startsWith('setup.'));
+}
+export function parseSettingValue(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new KitError(422, 'E_SETTING_JSON', 'القيمة يجب أن تكون JSON صالحاً');
+    }
+}
+function settingKey(value) {
+    if (typeof value !== 'string' || !/^[a-z][a-z0-9_.-]{0,99}$/i.test(value))
+        throw new KitError(422, 'E_SETTING_KEY', 'المفتاح يبدأ بحرف ويحوي حروفاً وأرقاماً ونقاطاً فقط');
+    return value;
+}
+function settingScope(value) {
+    if (!SETTING_SCOPES.includes(value))
+        throw new KitError(422, 'E_SETTING_SCOPE', 'النطاق غير معروف');
+    return value;
+}
+function toRow(row) {
+    return {
+        id: Number(row.id),
+        key: String(row.key),
+        scope: row.scope,
+        scopeId: String(row.scope_id),
+        value: row.value,
+        readOnly: isProtectedSetting(String(row.key)),
+    };
+}
+export class SettingsAdmin {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async list(scope, scopeId = '0') {
+        const rows = await this.db('settings')
+            .where({ scope: settingScope(scope), scope_id: scopeId })
+            .orderBy('key');
+        return rows.map(toRow);
+    }
+    async upsert(actorId, input) {
+        const key = settingKey(input.key);
+        const scope = settingScope(input.scope);
+        if (key === UI_PREFERENCES_KEY) {
+            if (scope !== 'system')
+                throw new KitError(422, 'E_SETTING_SCOPE', 'تفضيلات الواجهة تُضبط على مستوى النظام');
+            validateUiPreferences(input.value);
+        }
+        if (isProtectedSetting(key))
+            throw new KitError(403, 'E_SETTING_READ_ONLY', 'هذا المفتاح تشغيلي للقراءة فقط');
+        const serialized = JSON.stringify(input.value);
+        if (serialized === undefined)
+            throw new KitError(422, 'E_SETTING_JSON', 'القيمة يجب أن تكون JSON صالحاً');
+        return this.db.transaction(async (trx) => {
+            const scopeId = await this.scopeId(trx, scope, input.scopeId);
+            const [row] = await trx('settings')
+                .insert({ key, scope, scope_id: scopeId, value: serialized })
+                .onConflict(['key', 'scope', 'scope_id'])
+                .merge(['value'])
+                .returning('*');
+            await logActivity(trx, {
+                resource: RESOURCE,
+                recordId: row.id,
+                actorId,
+                action: 'upsert',
+                changes: { key, scope, scopeId, value: input.value },
+            });
+            return toRow(row);
+        });
+    }
+    async delete(actorId, id) {
+        return this.db.transaction(async (trx) => {
+            const row = await trx('settings').where('id', id).first();
+            if (!row)
+                throw new KitError(404, 'E_SETTING_NOT_FOUND', 'الإعداد غير موجود');
+            if (isProtectedSetting(row.key))
+                throw new KitError(403, 'E_SETTING_READ_ONLY', 'هذا المفتاح تشغيلي للقراءة فقط');
+            await trx('settings').where('id', id).delete();
+            await logActivity(trx, {
+                resource: RESOURCE,
+                recordId: id,
+                actorId,
+                action: 'delete',
+                changes: { key: row.key, scope: row.scope, scopeId: row.scope_id },
+            });
+        });
+    }
+    async scopeId(db, scope, value) {
+        if (scope === 'system')
+            return '0';
+        const id = Number(value);
+        if (!Number.isSafeInteger(id) || id <= 0)
+            throw new KitError(422, 'E_SETTING_SCOPE', 'معرّف النطاق مطلوب');
+        const table = scope === 'org_unit' ? 'org_units' : 'users';
+        if (!(await db(table).where('id', id).first('id')))
+            throw new KitError(404, 'E_SETTING_SCOPE', scope === 'org_unit' ? 'الوحدة التنظيمية غير موجودة' : 'المستخدم غير موجود');
+        return String(id);
+    }
+}

package/build/src/core/setup.d.ts

@@ -0,0 +1,14 @@
+import type { Knex } from 'knex';
+export type SetupCheck = {
+    status: 'checking' | 'passed' | 'failed';
+    checkedAt: string;
+    fingerprint: string;
+    attempt: string;
+};
+export declare class InitialSetup {
+    private db;
+    constructor(db: Knex);
+    check(actorId: number, name: 'storage' | 'infrastructure', fingerprint: string, probe: () => Promise<void>): Promise<void>;
+    acknowledgeIdentity(actorId: number, fingerprint: string): Promise<void>;
+    testNotification(actorId: number): Promise<number>;
+}