@adula/kit 1.0.0 → 1.2.0

package/build/src/core/roles.js

@@ -1,4 +1,5 @@
 import { conditionSql } from '../auth/sql.js';
+import { resolveActorConditions, usesActor } from '../auth/conditions.js';
 import { KitError } from '../admin/errors.js';
 import { logActivity } from './activity.js';
 import { administrationGuard } from './administration_guard.js';
@@ -11,6 +12,7 @@ function standardConditionFields(resource) {
         label: { ar, en },
         type: 'integer',
         conditionable: true,
+        ...(['createdBy', 'updatedBy'].includes(key) ? { actor: true } : {}),
     });
     return [
         field('id', 'المعرّف', 'ID'),
@@ -27,6 +29,7 @@ function matrixFields(resource) {
         label: field.label,
         type: field.type,
         conditionable: !['hasMany', 'json', 'attachment'].includes(field.type),
+        ...(field.type === 'user' ? { actor: true } : {}),
     }));
 }
 function roleName(value) {
@@ -35,6 +38,13 @@ function roleName(value) {
         throw new KitError(422, 'E_ROLE_NAME', 'اسم الدور مطلوب (حتى 100 حرف)');
     return name;
 }
+/** A role key: lower-case letters, digits and underscores, starting with a letter. */
+export function roleKey(value) {
+    const key = typeof value === 'string' ? value.trim() : '';
+    if (!/^[a-z][a-z0-9_]{0,99}$/.test(key))
+        throw new KitError(422, 'E_ROLE_KEY', 'مفتاح الدور حروف إنجليزية صغيرة وأرقام وشرطة سفلية، ويبدأ بحرف (مثل project_manager)');
+    return key;
+}
 function permissionLevel(value) {
     const level = Number(value ?? 0);
     if (!Number.isSafeInteger(level) || level < 0 || level > 9)
@@ -60,10 +70,11 @@ export class RolesAdmin {
     }
     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'))
+            .select('r.id', 'r.key', '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,
+            key: row.key ?? null,
             name: row.name,
             permissionLevel: row.permission_level,
             rules: Number(row.rules),
@@ -81,6 +92,7 @@ export class RolesAdmin {
             .first();
         return {
             id: role.id,
+            key: role.key ?? null,
             name: role.name,
             permissionLevel: role.permission_level,
             users: Number(users?.count ?? 0),
@@ -89,19 +101,48 @@ export class RolesAdmin {
     }
     async create(actorId, input) {
         const name = roleName(input.name);
+        const key = input.key === undefined || input.key === null || input.key === '' ? null : roleKey(input.key);
         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('*');
+            if (key && (await trx('roles').where('key', key).first()))
+                throw new KitError(409, 'E_ROLE_KEY_EXISTS', 'يوجد دور بهذا المفتاح');
+            const [role] = await trx('roles')
+                .insert({ name, key, permission_level: level })
+                .returning('*');
             await logActivity(trx, {
                 resource: RESOURCE,
                 recordId: role.id,
                 actorId,
                 action: 'create',
-                changes: { name, permissionLevel: level },
+                changes: { name, key, permissionLevel: level },
+            });
+            return { id: role.id, key, name, permissionLevel: level };
+        });
+    }
+    /**
+     * Gives a role its stable key. A key is set once: workflows and module defaults
+     * depend on it, so changing it would silently detach them.
+     */
+    async setKey(actorId, id, value) {
+        const key = roleKey(value);
+        return this.db.transaction(async (trx) => {
+            const role = await this.find(trx, id);
+            if (role.key === key)
+                return;
+            if (role.key)
+                throw new KitError(409, 'E_ROLE_KEY_FIXED', 'مفتاح الدور ثابت بعد تعيينه لأن تدفقات العمل والوحدات تعتمد عليه');
+            if (await trx('roles').where('key', key).whereNot('id', id).first())
+                throw new KitError(409, 'E_ROLE_KEY_EXISTS', 'يوجد دور بهذا المفتاح');
+            await trx('roles').where('id', id).update({ key });
+            await logActivity(trx, {
+                resource: RESOURCE,
+                recordId: id,
+                actorId,
+                action: 'set_key',
+                changes: { key },
             });
-            return { id: role.id, name, permissionLevel: level };
         });
     }
     async rename(actorId, id, value) {
@@ -249,6 +290,81 @@ export class RolesAdmin {
             });
         });
     }
+    /**
+     * Creates module default roles that no role holds the key of yet, with their rules
+     * validated exactly like setRule. Existing roles are never modified. A keyless role
+     * with the same display name is adopted by receiving the key, rules untouched.
+     */
+    async ensureDefaults(actorId, roles) {
+        const prepared = roles.map((role) => {
+            const key = roleKey(role.key);
+            const name = roleName(role.name);
+            const level = permissionLevel(role.permissionLevel);
+            const rules = role.rules.map((rule) => {
+                try {
+                    return this.validateRule(rule);
+                }
+                catch (error) {
+                    throw new Error(`Default role ${key}: ${error.message}`);
+                }
+            });
+            return { key, name, level, rules };
+        });
+        const result = { created: [], adopted: [], kept: [] };
+        await this.db.transaction(async (trx) => {
+            for (const role of prepared) {
+                if (await trx('roles').where('key', role.key).first('id')) {
+                    result.kept.push(role.key);
+                    continue;
+                }
+                const named = await trx('roles').where('name', role.name).first();
+                if (named) {
+                    // A role with this name but another key belongs to the administrator.
+                    if (named.key) {
+                        result.kept.push(role.key);
+                        continue;
+                    }
+                    await trx('roles').where('id', named.id).update({ key: role.key });
+                    await logActivity(trx, {
+                        resource: RESOURCE,
+                        recordId: named.id,
+                        actorId,
+                        action: 'set_key',
+                        changes: { key: role.key, source: 'module default' },
+                    });
+                    result.adopted.push(role.key);
+                    continue;
+                }
+                const [created] = await trx('roles')
+                    .insert({ key: role.key, name: role.name, permission_level: role.level })
+                    .returning('id');
+                for (const rule of role.rules)
+                    await trx('role_rules').insert({
+                        role_id: created.id,
+                        subject: rule.subject,
+                        action: rule.action,
+                        inverted: rule.inverted,
+                        conditions: rule.conditions ? JSON.stringify(rule.conditions) : null,
+                        fields: rule.fields ? JSON.stringify(rule.fields) : null,
+                    });
+                await logActivity(trx, {
+                    resource: RESOURCE,
+                    recordId: created.id,
+                    actorId,
+                    action: 'create',
+                    changes: {
+                        name: role.name,
+                        key: role.key,
+                        permissionLevel: role.level,
+                        rules: role.rules.length,
+                        source: 'module default',
+                    },
+                });
+                result.created.push(role.key);
+            }
+        });
+        return result;
+    }
     validateRule(input) {
         const subject = typeof input.subject === 'string' ? input.subject : '';
         let resource;
@@ -287,8 +403,20 @@ export class RolesAdmin {
             for (const field of Object.keys(input.conditions))
                 if (!conditionable.has(field))
                     throw new KitError(422, 'E_RULE_CONDITIONS', `الحقل ${field} لا يقبل الشروط`);
+            const actorFields = new Set([...standardConditionFields(resource), ...matrixFields(resource)]
+                .filter((field) => field.actor)
+                .map((field) => field.key));
+            for (const [field, condition] of Object.entries(input.conditions))
+                if (usesActor({ [field]: condition })) {
+                    if (!actorFields.has(field))
+                        throw new KitError(422, 'E_RULE_CONDITIONS', `المستخدم الحالي يُستخدم مع حقول المستخدمين وأنشأه وعدّله فقط: ${field}`);
+                    const operators = condition !== null && typeof condition === 'object' ? Object.keys(condition) : ['$eq'];
+                    if (operators.some((operator) => !['$eq', '$ne', '$in'].includes(operator)))
+                        throw new KitError(422, 'E_RULE_CONDITIONS', 'المستخدم الحالي يقبل عوامل يساوي ولا يساوي وضمن قائمة فقط');
+                }
             try {
-                conditionSql(input.conditions, resource);
+                // The placeholder is an integer id at request time; validate it as one.
+                conditionSql(resolveActorConditions(input.conditions, 1), resource);
             }
             catch (error) {
                 throw new KitError(422, 'E_RULE_CONDITIONS', `شرط غير مدعوم: ${error.message}`);

package/build/src/database/schema.d.ts

@@ -9,6 +9,11 @@ export declare function createResourceTable(db: Knex, resource: Pick<Resource, '
 export declare function createCollaborationSchema(db: Knex): Promise<void>;
 /** Work assigned to a user on a record; approval steps of workflows reuse it (phase 4). */
 export declare function createAssignmentsSchema(db: Knex): Promise<void>;
+/**
+ * Managed assignments (1.1): opened and closed by module code with the record's state,
+ * never completed by hand. The close reason is shown with the closed task.
+ */
+export declare function createManagedAssignmentsSchema(db: Knex): Promise<void>;
 /**
  * Message templates, notification e-mail delivery state and the realtime signal.
  * The trigger's NOTIFY is delivered only when the inserting transaction commits.
@@ -23,3 +28,25 @@ export declare function createImportsSchema(db: Knex): Promise<void>;
  * columns, and every transition is appended to workflow_events.
  */
 export declare function createWorkflowSchema(db: Knex): Promise<void>;
+/**
+ * Roles gain a stable key (1.1) that workflows and module defaults address, so an
+ * administrator can rename the display name freely. Existing identifier-like names
+ * (such as the bootstrap "administrator") become their key.
+ */
+export declare function createRoleKeysSchema(db: Knex): Promise<void>;
+/**
+ * Notifications may name the record they are about (1.1). Links are authorized when
+ * opened, by the record page itself, never when the notification is written.
+ */
+export declare function createNotificationTargetsSchema(db: Knex): Promise<void>;
+/**
+ * Short-lived upload grants (1.1): module code lets one user upload to one attachment field
+ * of one record without a role rule. Only the SHA-256 hash of the token is stored.
+ */
+export declare function createUploadGrantsSchema(db: Knex): Promise<void>;
+/**
+ * Signed inbound webhooks (1.2): administrator-managed sources with sealed secrets,
+ * and a delivery log deduplicated by the sender's delivery id. Accepted deliveries are
+ * dispatched as domain events through the outbox.
+ */
+export declare function createInboundWebhooksSchema(db: Knex): Promise<void>;

package/build/src/database/schema.js

@@ -199,6 +199,10 @@ export async function createResourceTable(db, resource) {
                     column = t.integer(name);
                     column.references('id').inTable('attachments').onDelete('RESTRICT').index();
                     break;
+                case 'user':
+                    column = t.integer(name);
+                    column.references('id').inTable('users').onDelete('RESTRICT').index();
+                    break;
                 case 'integer':
                     column = t.integer(name);
                     break;
@@ -329,6 +333,16 @@ export async function createAssignmentsSchema(db) {
         t.index(['workflow_run_id']);
     });
 }
+/**
+ * Managed assignments (1.1): opened and closed by module code with the record's state,
+ * never completed by hand. The close reason is shown with the closed task.
+ */
+export async function createManagedAssignmentsSchema(db) {
+    await db.schema.alterTable('assignments', (t) => {
+        t.boolean('managed').notNullable().defaultTo(false);
+        t.string('close_reason', 500);
+    });
+}
 /**
  * Message templates, notification e-mail delivery state and the realtime signal.
  * The trigger's NOTIFY is delivered only when the inserting transaction commits.
@@ -438,3 +452,87 @@ export async function createWorkflowSchema(db) {
         t.index(['run_id', 'id']);
     });
 }
+/**
+ * Roles gain a stable key (1.1) that workflows and module defaults address, so an
+ * administrator can rename the display name freely. Existing identifier-like names
+ * (such as the bootstrap "administrator") become their key.
+ */
+export async function createRoleKeysSchema(db) {
+    await db.schema.alterTable('roles', (t) => {
+        t.string('key', 100).unique();
+    });
+    await db.raw("UPDATE roles SET key = name WHERE name ~ '^[a-z][a-z0-9_]*$'");
+}
+/**
+ * Notifications may name the record they are about (1.1). Links are authorized when
+ * opened, by the record page itself, never when the notification is written.
+ */
+export async function createNotificationTargetsSchema(db) {
+    await db.schema.alterTable('notifications', (t) => {
+        t.string('resource', 100);
+        t.integer('record_id');
+    });
+}
+/**
+ * Short-lived upload grants (1.1): module code lets one user upload to one attachment field
+ * of one record without a role rule. Only the SHA-256 hash of the token is stored.
+ */
+export async function createUploadGrantsSchema(db) {
+    await db.schema.createTable('upload_grants', (t) => {
+        t.increments('id');
+        t.string('token_hash', 64).notNullable().unique();
+        t.integer('user_id').notNullable().references('users.id').onDelete('CASCADE');
+        t.string('resource', 100).notNullable();
+        t.integer('record_id').notNullable();
+        t.string('field', 100).notNullable();
+        t.integer('org_unit_id');
+        t.timestamp('expires_at', { useTz: true }).notNullable();
+        t.integer('created_by').notNullable();
+        t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.index(['expires_at']);
+    });
+}
+/**
+ * Signed inbound webhooks (1.2): administrator-managed sources with sealed secrets,
+ * and a delivery log deduplicated by the sender's delivery id. Accepted deliveries are
+ * dispatched as domain events through the outbox.
+ */
+export async function createInboundWebhooksSchema(db) {
+    await db.schema.createTable('inbound_sources', (t) => {
+        t.increments('id');
+        t.string('key', 60).notNullable().unique();
+        t.string('name', 100).notNullable();
+        t.text('secret').notNullable();
+        t.string('algorithm', 10).notNullable().defaultTo('sha256');
+        t.string('signature_header', 100).notNullable().defaultTo('x-hub-signature-256');
+        t.string('signature_prefix', 20).notNullable().defaultTo('sha256=');
+        t.string('event_header', 100).notNullable().defaultTo('x-github-event');
+        t.string('delivery_header', 100).notNullable().defaultTo('x-github-delivery');
+        t.boolean('dedupe_body').notNullable().defaultTo(true);
+        t.boolean('active').notNullable().defaultTo(true);
+        t.integer('created_by').references('id').inTable('users').onDelete('SET NULL');
+        t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.timestamp('updated_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.timestamp('last_received_at', { useTz: true });
+    });
+    await db.schema.createTable('inbound_deliveries', (t) => {
+        t.uuid('id').primary();
+        t.integer('source_id')
+            .notNullable()
+            .references('id')
+            .inTable('inbound_sources')
+            .onDelete('CASCADE');
+        t.string('delivery_id', 200).notNullable();
+        /** SHA-256 of the raw body while the source deduplicates bodies; null otherwise. */
+        t.string('body_key', 64);
+        t.string('event', 100).notNullable();
+        t.jsonb('payload').notNullable();
+        t.uuid('event_id').notNullable();
+        t.integer('dispatches').notNullable().defaultTo(1);
+        t.timestamp('received_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.unique(['source_id', 'delivery_id']);
+        t.unique(['source_id', 'body_key']);
+        t.index(['source_id', 'received_at']);
+        t.index(['received_at']);
+    });
+}

package/build/src/eslint/index.js

@@ -42,6 +42,32 @@ export default {
         }
       },
     },
+    'no-system-save-in-controllers': {
+      meta: {
+        type: 'problem',
+        schema: [],
+        messages: {
+          forbidden:
+            'systemSave and rehome skip role rules. Call them from listeners or module services after an explicit authorization, never from a controller or route.',
+        },
+      },
+      create(context) {
+        const file = context.filename.replaceAll('\\', '/')
+        // Request handlers act for a user, so their writes go through save() and its rules.
+        if (!/(?:^|\/)(?:app\/controllers|app\/modules\/[^/]+\/controllers)\/|(?:^|\/)start\/routes\./.test(file))
+          return {}
+        return {
+          CallExpression(node) {
+            if (
+              node.callee.type === 'MemberExpression' &&
+              node.callee.property.type === 'Identifier' &&
+              ['systemSave', 'rehome'].includes(node.callee.property.name)
+            )
+              context.report({ node, messageId: 'forbidden' })
+          },
+        }
+      },
+    },
     'no-kit-patching': {
       meta: {
         type: 'problem',

package/build/src/events/record_mutation.d.ts

@@ -17,4 +17,8 @@ export declare function recordMutation(trx: Knex.Transaction, mutation: {
     fields: string[];
     /** Before/after values of the changed fields; read back per viewer's field access. */
     changes?: FieldChange[];
+    /** Written by module code through ResourceService.systemSave, not by a user's edit. */
+    system?: boolean;
+    /** Why module code made the change; shown with the activity entry. */
+    reason?: string;
 }): Promise<void>;

package/build/src/events/record_mutation.js

@@ -28,6 +28,8 @@ export async function recordMutation(trx, mutation) {
         changes: JSON.stringify({
             fields: mutation.fields,
             ...(mutation.impersonatorId ? { impersonatedBy: mutation.impersonatorId } : {}),
+            ...(mutation.system ? { system: true } : {}),
+            ...(mutation.reason ? { reason: mutation.reason } : {}),
         }),
     })
         .returning('id');

package/build/src/integrations/imports.js

@@ -20,7 +20,8 @@ export function importCell(field, raw, lookups) {
     const latin = value.replace(/[٠-٩]/g, (digit) => String(digit.charCodeAt(0) - 0x0660));
     switch (field.type) {
         case 'integer':
-        case 'belongsTo': {
+        case 'belongsTo':
+        case 'user': {
             if (!/^-?\d+$/.test(latin))
                 throw new Error('رقم صحيح مطلوب');
             return Number(latin);
@@ -108,7 +109,8 @@ export class ImportBatches {
             type: resource.fields[key].type,
             required: Boolean(resource.fields[key].required),
         }));
-        if (resource.scoped)
+        // An inherited scope takes the unit from the parent row instead (#45).
+        if (resource.scoped && !resource.scope)
             fields.push({
                 key: 'orgUnitId',
                 label: 'الوحدة التنظيمية (رقم)',

package/build/src/integrations/inbound_webhooks.d.ts

@@ -0,0 +1,94 @@
+import type { Knex } from 'knex';
+import type { SecretBox } from './webhooks.js';
+export type InboundSource = {
+    id: number;
+    key: string;
+    name: string;
+    algorithm: 'sha256' | 'sha512';
+    signatureHeader: string;
+    signaturePrefix: string;
+    eventHeader: string;
+    deliveryHeader: string;
+    /** Refuse a body already received from this source, whatever its delivery id or event. */
+    dedupeBody: boolean;
+    active: boolean;
+    createdAt: string;
+    lastReceivedAt: string | null;
+    /** The path senders post to. */
+    path: string;
+};
+export type InboundSourceInput = {
+    key?: unknown;
+    name?: unknown;
+    algorithm?: unknown;
+    signatureHeader?: unknown;
+    signaturePrefix?: unknown;
+    eventHeader?: unknown;
+    deliveryHeader?: unknown;
+    dedupeBody?: unknown;
+    active?: unknown;
+};
+export type InboundDelivery = {
+    id: string;
+    deliveryId: string;
+    event: string;
+    eventName: string;
+    dispatches: number;
+    receivedAt: string;
+};
+export type InboundReceipt = {
+    delivery: string;
+    event: string;
+    duplicate: boolean;
+};
+/** Inbound payloads above this size are refused before verification. */
+export declare const INBOUND_BODY_LIMIT: number;
+/** Stored deliveries older than this are removed by pruneDeliveries(). */
+export declare const INBOUND_RETENTION_DAYS = 90;
+/** The domain event an inbound delivery raises: inbound.<source>.<event>. */
+export declare function inboundEventName(source: string, event: string): string;
+/**
+ * Signed inbound webhooks (#30). Administrators create a source per sender (for example
+ * a Git host) and give it the generated secret. POST /webhooks/in/<key> verifies an
+ * HMAC over the raw body in constant time (X-Hub-Signature-256 by default), stores each
+ * delivery once by the sender's delivery id and raises inbound.<key>.<event> through the
+ * outbox, so module listeners run idempotently with retries and a delivery history.
+ */
+export declare class InboundWebhooks {
+    private db;
+    private secrets;
+    constructor(db: Knex, secrets: SecretBox);
+    list(): Promise<InboundSource[]>;
+    /** Creates a source and returns its secret once; it is never shown again. */
+    create(actorId: number, input: InboundSourceInput): Promise<{
+        source: InboundSource;
+        secret: string;
+    }>;
+    /**
+     * Updates the fields given (name, algorithm, headers, body deduplication, state); fields
+     * left out keep their stored values. The key and secret stay.
+     */
+    update(id: number, input: InboundSourceInput): Promise<void>;
+    /** Issues a new secret; the old one stops verifying at once. */
+    rotate(id: number): Promise<string>;
+    remove(id: number): Promise<void>;
+    /**
+     * Verifies and records one delivery. Unknown or inactive sources and bad signatures
+     * are refused without storing anything; a repeated delivery id is acknowledged once.
+     */
+    receive(key: string, request: {
+        headers: Record<string, string | string[] | undefined>;
+        body: string | Buffer;
+    }): Promise<InboundReceipt>;
+    deliveries(sourceId: number, limit?: number): Promise<InboundDelivery[]>;
+    /**
+     * Raises a stored delivery again as a new domain event, for listeners that failed or
+     * were added later. Listeners must be idempotent on the delivery id.
+     */
+    redispatch(deliveryId: string): Promise<void>;
+    /** Removes stored deliveries older than the retention period (90 days by default). */
+    pruneDeliveries(days?: number): Promise<number>;
+    private envelope;
+    private validate;
+    private present;
+}