@adula/kit 0.2.0-alpha.1

package/build/src/core/administration_guard.js

@@ -0,0 +1,37 @@
+import { buildAbility } from '../auth/ability.js';
+import { KitError } from '../admin/errors.js';
+/** Same CASL decision as the admin middleware, with fresh rows inside the transaction. */
+async function administrators(db) {
+    const rows = await db('user_roles as ur')
+        .join('users as u', 'u.id', 'ur.user_id')
+        .join('role_rules as rr', 'rr.role_id', 'ur.role_id')
+        .whereNull('u.disabled_at')
+        .whereNull('ur.org_unit_id')
+        .where('rr.subject', 'all')
+        .select('ur.user_id', 'rr.subject', 'rr.action', 'rr.inverted', 'rr.conditions', 'rr.fields');
+    const users = new Map();
+    for (const row of rows) {
+        const rules = users.get(row.user_id) ?? [];
+        rules.push({
+            subject: row.subject,
+            action: row.action,
+            inverted: row.inverted,
+            conditions: row.conditions ?? undefined,
+            fields: row.fields ?? undefined,
+        });
+        users.set(row.user_id, rules);
+    }
+    return new Set([...users].filter(([, rules]) => buildAbility(rules).can('manage', 'all')).map(([id]) => id));
+}
+/** Serialize access-changing mutations, including simultaneous requests by different admins. */
+export async function administrationGuard(trx, actorId) {
+    await trx.raw('SELECT pg_advisory_xact_lock(717011)');
+    const before = await administrators(trx);
+    return async () => {
+        const after = await administrators(trx);
+        if (before.size && !after.size)
+            throw new KitError(409, 'E_LAST_ADMIN', 'لا يمكن تنفيذ هذا التغيير لأنه سيزيل آخر مدير نشط للنظام. عيّن مديرًا آخر أولًا.');
+        if (before.has(actorId) && !after.has(actorId))
+            throw new KitError(409, 'E_SELF_ADMIN_ACCESS', 'لا يمكنك إزالة صلاحية إدارة النظام من حسابك الحالي. اطلب من مدير آخر تعديلها.');
+    };
+}

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

@@ -0,0 +1,42 @@
+import type { Knex } from 'knex';
+export type HeartbeatStatus = {
+    at: string | null;
+    ageMs: number | null;
+    healthy: boolean;
+};
+export type FailedJob = {
+    id: string;
+    name: string;
+    attemptsMade: number;
+    failedReason: string;
+    failedAt: string | null;
+};
+export type QueueCounts = Record<'waiting' | 'active' | 'delayed' | 'failed' | 'completed', number>;
+/** Filled by the host from its queue backend; the kit never talks to BullMQ. */
+export type QueueSnapshot = {
+    name: string;
+    counts: QueueCounts;
+    failed: FailedJob[];
+};
+export type RuntimeHealth = {
+    outbox: {
+        backlog: number;
+        oldestAgeMs: number | null;
+    };
+    processedEvents: number;
+    heartbeats: {
+        scheduler: HeartbeatStatus;
+        worker: HeartbeatStatus;
+    };
+    backup: {
+        lastOffsite: string | null;
+        lastRestoreTest: string | null;
+        stale: boolean;
+    };
+};
+export declare const HEARTBEAT_MAX_AGE_MS = 60000;
+export declare const BACKUP_MAX_AGE_MS: number;
+export declare function heartbeat(value: unknown, now?: number): HeartbeatStatus;
+export declare function backupStale(lastOffsite: unknown, now?: number): boolean;
+export declare function isBackupStale(db: Knex, now?: number): Promise<boolean>;
+export declare function runtimeHealth(db: Knex, now?: number): Promise<RuntimeHealth>;

package/build/src/core/health.js

@@ -0,0 +1,44 @@
+import { Settings } from '../services/settings.js';
+export const HEARTBEAT_MAX_AGE_MS = 60_000;
+export const BACKUP_MAX_AGE_MS = 48 * 3_600_000;
+function age(value, now) {
+    const at = typeof value === 'string' ? Date.parse(value) : Number.NaN;
+    return Number.isFinite(at) ? now - at : null;
+}
+export function heartbeat(value, now = Date.now()) {
+    const ageMs = age(value, now);
+    return {
+        at: ageMs === null ? null : String(value),
+        ageMs,
+        healthy: ageMs !== null && ageMs >= 0 && ageMs < HEARTBEAT_MAX_AGE_MS,
+    };
+}
+export function backupStale(lastOffsite, now = Date.now()) {
+    const ageMs = age(lastOffsite, now);
+    return ageMs === null || ageMs < 0 || ageMs >= BACKUP_MAX_AGE_MS;
+}
+export async function isBackupStale(db, now = Date.now()) {
+    return backupStale(await new Settings(db).get('backup.lastOffsite'), now);
+}
+export async function runtimeHealth(db, now = Date.now()) {
+    const settings = new Settings(db);
+    const outbox = await db('outbox')
+        .whereNull('published_at')
+        .select(db.raw('count(*) AS backlog'), db.raw('min(created_at) AS oldest'))
+        .first();
+    const processed = await db('processed_events').count('event_id as count').first();
+    const lastOffsite = (await settings.get('backup.lastOffsite')) ?? null;
+    const lastRestoreTest = (await settings.get('backup.lastRestoreTest')) ?? null;
+    return {
+        outbox: {
+            backlog: Number(outbox?.backlog ?? 0),
+            oldestAgeMs: outbox?.oldest ? Math.max(0, now - new Date(outbox.oldest).getTime()) : null,
+        },
+        processedEvents: Number(processed?.count ?? 0),
+        heartbeats: {
+            scheduler: heartbeat(await settings.get('scheduler.heartbeat'), now),
+            worker: heartbeat(await settings.get('worker.heartbeat'), now),
+        },
+        backup: { lastOffsite, lastRestoreTest, stale: backupStale(lastOffsite, now) },
+    };
+}

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

@@ -0,0 +1,18 @@
+import type { Knex } from 'knex';
+export declare const MAIL_TEST_KEY = "mail.delivery_test";
+export type MailTestState = {
+    id: string;
+    recipient: string;
+    fingerprint: string;
+    status: 'sending' | 'pending' | 'confirmed' | 'not_received' | 'failed';
+    requestedAt: string;
+    answeredAt?: string;
+};
+/** Receipt is an administrator attestation, never inferred from SMTP acceptance. */
+export declare class MailDeliveryTest {
+    private db;
+    constructor(db: Knex);
+    current(actorId: number, recipient: string, fingerprint: string): Promise<MailTestState | null>;
+    send(actorId: number, recipient: string, fingerprint: string, deliver: (id: string) => Promise<void>): Promise<void>;
+    answer(actorId: number, recipient: string, fingerprint: string, id: unknown, received: unknown): Promise<void>;
+}

package/build/src/core/mail_test.js

@@ -0,0 +1,88 @@
+import { randomUUID } from 'node:crypto';
+import { KitError } from '../admin/errors.js';
+import { Settings } from '../services/settings.js';
+import { logActivity } from './activity.js';
+export const MAIL_TEST_KEY = 'mail.delivery_test';
+/** Receipt is an administrator attestation, never inferred from SMTP acceptance. */
+export class MailDeliveryTest {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async current(actorId, recipient, fingerprint) {
+        const state = await new Settings(this.db).get(MAIL_TEST_KEY, 'user', String(actorId));
+        return state?.recipient === recipient && state.fingerprint === fingerprint ? state : null;
+    }
+    async send(actorId, recipient, fingerprint, deliver) {
+        const state = {
+            id: randomUUID(),
+            recipient,
+            fingerprint,
+            status: 'sending',
+            requestedAt: new Date().toISOString(),
+        };
+        await this.db.transaction(async (trx) => {
+            await trx.raw('SELECT pg_advisory_xact_lock(?, ?)', [717012, actorId]);
+            const previous = await new Settings(trx).get(MAIL_TEST_KEY, 'user', String(actorId));
+            const cooldown = previous?.status === 'sending' ? 300_000 : 60_000;
+            if (previous && Date.now() - Date.parse(previous.requestedAt) < cooldown)
+                throw new KitError(429, 'E_MAIL_TEST_COOLDOWN', 'انتظر قليلًا قبل إعادة إرسال البريد التجريبي');
+            await new Settings(trx).set(MAIL_TEST_KEY, state, 'user', String(actorId));
+            await logActivity(trx, {
+                resource: 'core.mail',
+                recordId: actorId,
+                actorId,
+                action: 'test_requested',
+                changes: { testId: state.id },
+            });
+        });
+        let failed = false;
+        try {
+            await deliver(state.id);
+        }
+        catch {
+            failed = true;
+        }
+        // Match the attempt so a delayed response cannot overwrite a newer test.
+        await this.db.transaction(async (trx) => {
+            await trx('settings')
+                .where({ key: MAIL_TEST_KEY, scope: 'user', scope_id: String(actorId) })
+                .whereRaw("value->>'id' = ?", [state.id])
+                .update({ value: JSON.stringify({ ...state, status: failed ? 'failed' : 'pending' }) });
+            await logActivity(trx, {
+                resource: 'core.mail',
+                recordId: actorId,
+                actorId,
+                action: failed ? 'test_send_failed' : 'test_send_accepted',
+                changes: { testId: state.id },
+            });
+        });
+        if (failed)
+            throw new KitError(502, 'E_MAIL_TEST_SEND', 'تعذّر إرسال البريد التجريبي. راجع إعدادات البريد ثم أعد المحاولة.');
+    }
+    async answer(actorId, recipient, fingerprint, id, received) {
+        if (typeof received !== 'boolean' || typeof id !== 'string')
+            throw new KitError(422, 'E_MAIL_TEST_ANSWER', 'اختر هل وصلت الرسالة أم لم تصل');
+        await this.db.transaction(async (trx) => {
+            await trx.raw('SELECT pg_advisory_xact_lock(?, ?)', [717012, actorId]);
+            const state = await new MailDeliveryTest(trx).current(actorId, recipient, fingerprint);
+            if (!state ||
+                state.id !== id ||
+                state.status !== 'pending' ||
+                Date.now() - Date.parse(state.requestedAt) > 86_400_000)
+                throw new KitError(409, 'E_MAIL_TEST_STALE', 'هذه التجربة لم تعد قابلة للتأكيد. أرسل رسالة تجريبية جديدة.');
+            await new Settings(trx).set(MAIL_TEST_KEY, {
+                ...state,
+                status: received ? 'confirmed' : 'not_received',
+                answeredAt: new Date().toISOString(),
+            }, 'user', String(actorId));
+            await logActivity(trx, {
+                resource: 'core.mail',
+                recordId: actorId,
+                actorId,
+                action: received ? 'receipt_confirmed' : 'receipt_missing',
+                changes: { testId: state.id },
+            });
+        });
+    }
+}

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

@@ -0,0 +1,25 @@
+import type { Knex } from 'knex';
+export type Notification = {
+    id: number;
+    title: string;
+    body: string;
+    readAt: string | null;
+    createdAt: string;
+};
+export type NotificationPage = {
+    data: Notification[];
+    nextCursor: string | null;
+    unread: number;
+};
+export declare class NotificationsAdmin {
+    private db;
+    constructor(db: Knex);
+    /** Unread first, newest first; the cursor remembers which of the two segments it is in. */
+    list(userId: number, options?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<NotificationPage>;
+    markRead(userId: number, id: number): Promise<void>;
+    markAllRead(userId: number): Promise<number>;
+    unreadCount(userId: number): Promise<number>;
+}

package/build/src/core/notifications.js

@@ -0,0 +1,65 @@
+import { KitError } from '../admin/errors.js';
+import { pageLimit } from './activity.js';
+export class NotificationsAdmin {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** Unread first, newest first; the cursor remembers which of the two segments it is in. */
+    async list(userId, options = {}) {
+        const limit = pageLimit(options.limit);
+        const query = this.db('notifications')
+            .where('user_id', userId)
+            .orderByRaw('(read_at IS NULL) DESC, id DESC')
+            .limit(limit + 1);
+        if (options.cursor) {
+            const match = /^([ur]):(\d{1,18})$/.exec(options.cursor);
+            if (!match)
+                throw new KitError(422, 'E_NOTIFICATION_CURSOR', 'مؤشر الصفحة غير صالح');
+            const id = Number(match[2]);
+            if (match[1] === 'u')
+                query.where((where) => where
+                    .where((unread) => unread.whereNull('read_at').where('id', '<', id))
+                    .orWhereNotNull('read_at'));
+            else
+                query.whereNotNull('read_at').where('id', '<', id);
+        }
+        const rows = await query;
+        const page = rows.slice(0, limit);
+        const last = page[page.length - 1];
+        return {
+            data: page.map((row) => ({
+                id: row.id,
+                title: row.title,
+                body: row.body,
+                readAt: row.read_at ? new Date(row.read_at).toISOString() : null,
+                createdAt: new Date(row.created_at).toISOString(),
+            })),
+            nextCursor: rows.length > limit ? `${last.read_at ? 'r' : 'u'}:${last.id}` : null,
+            unread: await this.unreadCount(userId),
+        };
+    }
+    async markRead(userId, id) {
+        const owned = await this.db('notifications').where({ id, user_id: userId }).first('id');
+        if (!owned)
+            throw new KitError(404, 'E_NOTIFICATION_NOT_FOUND', 'الإشعار غير موجود');
+        await this.db('notifications')
+            .where({ id, user_id: userId })
+            .whereNull('read_at')
+            .update({ read_at: this.db.fn.now() });
+    }
+    async markAllRead(userId) {
+        return this.db('notifications')
+            .where('user_id', userId)
+            .whereNull('read_at')
+            .update({ read_at: this.db.fn.now() });
+    }
+    async unreadCount(userId) {
+        const row = await this.db('notifications')
+            .where('user_id', userId)
+            .whereNull('read_at')
+            .count('id as count')
+            .first();
+        return Number(row?.count ?? 0);
+    }
+}

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

@@ -0,0 +1,30 @@
+import type { Knex } from 'knex';
+import type { ResourceRegistry } from '../resource/registry.js';
+export type OrgUnitNode = {
+    id: number;
+    parentId: number | null;
+    name: string;
+    type: string;
+    path: string;
+    depth: number;
+    members: number;
+};
+export declare class OrgUnitsAdmin {
+    private db;
+    private registry;
+    constructor(db: Knex, registry: ResourceRegistry);
+    tree(): Promise<OrgUnitNode[]>;
+    create(actorId: number, input: {
+        parentId: number | null;
+        name: string;
+        type: string;
+    }): Promise<{
+        id: number;
+        path: string;
+    }>;
+    rename(actorId: number, id: number, value: string): Promise<void>;
+    move(actorId: number, id: number, parentId: number | null): Promise<void>;
+    /** A unit leaves only when nothing points at it: children, memberships or scoped records. */
+    delete(actorId: number, id: number): Promise<void>;
+    private find;
+}

package/build/src/core/org_units.js

@@ -0,0 +1,123 @@
+import { randomBytes } from 'node:crypto';
+import { identifier } from '../resource/define_resource.js';
+import { KitError } from '../admin/errors.js';
+import { moveOrgUnit } from '../org/org_service.js';
+import { logActivity } from './activity.js';
+const RESOURCE = 'core.org_units';
+// Shared with moveOrgUnit so every tree edit serializes on the same lock.
+const TREE_LOCK = 717010;
+function text(value, field) {
+    const trimmed = typeof value === 'string' ? value.trim() : '';
+    if (!trimmed || trimmed.length > 100)
+        throw new KitError(422, 'E_ORG_INPUT', `${field} مطلوب (حتى 100 حرف)`);
+    return trimmed;
+}
+export class OrgUnitsAdmin {
+    db;
+    registry;
+    constructor(db, registry) {
+        this.db = db;
+        this.registry = registry;
+    }
+    async tree() {
+        const rows = await this.db('org_units as o')
+            .select('o.id', 'o.parent_id', 'o.name', 'o.type', this.db.raw('o.path::text AS path'), this.db.raw('nlevel(o.path) AS depth'), this.db.raw('(SELECT count(*) FROM user_org_units m WHERE m.org_unit_id = o.id) AS members'))
+            .orderBy('o.path');
+        return rows.map((row) => ({
+            id: row.id,
+            parentId: row.parent_id ?? null,
+            name: row.name,
+            type: row.type,
+            path: row.path,
+            depth: Number(row.depth),
+            members: Number(row.members),
+        }));
+    }
+    async create(actorId, input) {
+        const name = text(input.name, 'الاسم');
+        const type = text(input.type, 'النوع');
+        return this.db.transaction(async (trx) => {
+            await trx.raw('SELECT pg_advisory_xact_lock(?)', [TREE_LOCK]);
+            const parent = input.parentId === null ? null : await trx('org_units').where('id', input.parentId).first();
+            if (input.parentId !== null && !parent)
+                throw new KitError(404, 'E_ORG_NOT_FOUND', 'الوحدة الأم غير موجودة');
+            const [unit] = await trx('org_units')
+                .insert({
+                parent_id: input.parentId,
+                name,
+                type,
+                path: `tmp_${randomBytes(8).toString('hex')}`,
+            })
+                .returning('id');
+            const path = parent ? `${parent.path}.${unit.id}` : `${unit.id}`;
+            await trx('org_units').where('id', unit.id).update({ path });
+            await logActivity(trx, {
+                resource: RESOURCE,
+                recordId: unit.id,
+                actorId,
+                action: 'create',
+                changes: { name, type, parentId: input.parentId, path },
+            });
+            return { id: unit.id, path };
+        });
+    }
+    async rename(actorId, id, value) {
+        const name = text(value, 'الاسم');
+        return this.db.transaction(async (trx) => {
+            const unit = await this.find(trx, id);
+            await trx('org_units').where('id', id).update({ name });
+            await logActivity(trx, {
+                resource: RESOURCE,
+                recordId: id,
+                actorId,
+                action: 'rename',
+                changes: { from: unit.name, to: name },
+            });
+        });
+    }
+    async move(actorId, id, parentId) {
+        return this.db.transaction(async (trx) => {
+            const unit = await this.find(trx, id);
+            await moveOrgUnit(trx, id, parentId);
+            const moved = await trx('org_units').where('id', id).first();
+            await logActivity(trx, {
+                resource: RESOURCE,
+                recordId: id,
+                actorId,
+                action: 'move',
+                changes: { from: unit.parent_id ?? null, to: parentId, path: String(moved.path) },
+            });
+        });
+    }
+    /** A unit leaves only when nothing points at it: children, memberships or scoped records. */
+    async delete(actorId, id) {
+        return this.db.transaction(async (trx) => {
+            await trx.raw('SELECT pg_advisory_xact_lock(?)', [TREE_LOCK]);
+            const unit = await this.find(trx, id);
+            if (await trx('org_units').where('parent_id', id).first())
+                throw new KitError(409, 'E_ORG_HAS_CHILDREN', 'انقل الوحدات الفرعية أولاً');
+            if ((await trx('user_org_units').where('org_unit_id', id).first()) ||
+                (await trx('user_roles').where('org_unit_id', id).first()))
+                throw new KitError(409, 'E_ORG_HAS_MEMBERS', 'أزل أعضاء الوحدة وأدوارها المقيدة أولاً');
+            for (const resource of this.registry.all().filter((r) => r.scoped)) {
+                const record = await trx(identifier(resource.name)).where('org_unit_id', id).first('id');
+                if (record)
+                    throw new KitError(409, 'E_ORG_HAS_RECORDS', `الوحدة تحتوي سجلات في ${resource.label.ar}؛ انقلها أولاً`);
+            }
+            await trx('org_units').where('id', id).delete();
+            await logActivity(trx, {
+                resource: RESOURCE,
+                recordId: id,
+                actorId,
+                action: 'delete',
+                changes: { name: unit.name, path: String(unit.path) },
+            });
+        });
+    }
+    async find(db, id) {
+        const unit = await db('org_units').where('id', id).first();
+        if (!unit)
+            throw new KitError(404, 'E_ORG_NOT_FOUND', 'الوحدة التنظيمية غير موجودة');
+        return unit;
+    }
+}

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

@@ -0,0 +1,72 @@
+import type { Knex } from 'knex';
+import type { ResourceRegistry } from '../resource/registry.js';
+import type { Label } from '../resource/types.js';
+import type { Conditions } from '../auth/conditions.js';
+export type RoleSummary = {
+    id: number;
+    name: string;
+    permissionLevel: number;
+    rules: number;
+    users: number;
+};
+export type RoleRule = {
+    id: number;
+    subject: string;
+    action: string;
+    inverted: boolean;
+    conditions: Conditions | null;
+    fields: string[] | null;
+};
+export type RoleDetail = Omit<RoleSummary, 'rules'> & {
+    rules: RoleRule[];
+};
+export type RuleInput = {
+    subject: string;
+    action: string;
+    inverted?: boolean;
+    conditions?: Conditions | null;
+    fields?: string[] | null;
+};
+export type MatrixField = {
+    key: string;
+    label: Label;
+    type: string;
+    conditionable: boolean;
+};
+export type MatrixSubject = {
+    name: string;
+    label: Label;
+    actions: string[];
+    fields: MatrixField[];
+    /** Standard columns the resource actually has plus its conditionable fields. */
+    conditionFields: MatrixField[];
+};
+export type RoleMatrix = {
+    actions: string[];
+    subjects: MatrixSubject[];
+};
+export declare const ALL_SUBJECT_LABEL: Label;
+export declare class RolesAdmin {
+    private db;
+    private registry;
+    constructor(db: Knex, registry: ResourceRegistry);
+    list(): Promise<RoleSummary[]>;
+    get(id: number): Promise<RoleDetail>;
+    create(actorId: number, input: {
+        name: string;
+        permissionLevel?: number;
+    }): Promise<{
+        id: number;
+        name: string;
+        permissionLevel: number;
+    }>;
+    rename(actorId: number, id: number, value: string): Promise<void>;
+    setPermissionLevel(actorId: number, id: number, value: number): Promise<void>;
+    delete(actorId: number, id: number): Promise<void>;
+    /** Subjects × actions derived from the registry; the UI never hard-codes resources. */
+    matrix(): RoleMatrix;
+    setRule(actorId: number, roleId: number, input: RuleInput): Promise<RoleRule>;
+    removeRule(actorId: number, roleId: number, ruleId: number): Promise<void>;
+    private validateRule;
+    private find;
+}