@adula/kit 0.2.0-alpha.4 → 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

@@ -5,3 +5,48 @@ export declare function createCoreSchema(db: Knex): Promise<void>;
 export declare function createAttachmentsSchema(db: Knex): Promise<void>;
 export declare function createSavedViewsSchema(db: Knex): Promise<void>;
 export declare function createResourceTable(db: Knex, resource: Pick<Resource, 'name' | 'scoped' | 'version' | 'submittable' | 'customFields' | 'fields'>): Promise<void>;
+/** Record collaboration (phase 3): comments with mentions, followers, tags and field history. */
+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.
+ */
+export declare function createMessagingSchema(db: Knex): Promise<void>;
+/** Outgoing webhooks and their delivery log (exactly one row per webhook and event). */
+export declare function createWebhooksSchema(db: Knex): Promise<void>;
+/** CSV import batches: parsed rows, column mapping, progress and per-row errors. */
+export declare function createImportsSchema(db: Knex): Promise<void>;
+/**
+ * Workflow engine state (phase 4): the submission envelope rows gain execution
+ * 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;
@@ -246,3 +250,289 @@ export async function createResourceTable(db, resource) {
         await db.raw('CREATE INDEX ?? ON ?? USING gin(search_vector)', [`${table}_search_gin`, table]);
     }
 }
+/** Record collaboration (phase 3): comments with mentions, followers, tags and field history. */
+export async function createCollaborationSchema(db) {
+    await db.schema.createTable('comments', (t) => {
+        t.bigIncrements('id');
+        t.string('resource').notNullable();
+        t.integer('record_id').notNullable();
+        t.integer('author_id').notNullable().references('id').inTable('users').onDelete('RESTRICT');
+        t.text('body').notNullable();
+        t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.timestamp('edited_at', { useTz: true });
+        t.timestamp('deleted_at', { useTz: true });
+        t.index(['resource', 'record_id', 'id']);
+    });
+    await db.schema.createTable('comment_mentions', (t) => {
+        t.bigInteger('comment_id')
+            .notNullable()
+            .references('id')
+            .inTable('comments')
+            .onDelete('CASCADE');
+        t.integer('user_id').notNullable().references('id').inTable('users').onDelete('CASCADE');
+        t.primary(['comment_id', 'user_id']);
+        t.index(['user_id']);
+    });
+    await db.schema.createTable('followers', (t) => {
+        t.string('resource').notNullable();
+        t.integer('record_id').notNullable();
+        t.integer('user_id').notNullable().references('id').inTable('users').onDelete('CASCADE');
+        t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.primary(['resource', 'record_id', 'user_id']);
+        t.index(['user_id']);
+    });
+    await db.schema.createTable('tags', (t) => {
+        t.increments('id');
+        t.string('name', 60).notNullable().unique();
+        t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+    });
+    await db.schema.createTable('taggables', (t) => {
+        t.integer('tag_id').notNullable().references('id').inTable('tags').onDelete('CASCADE');
+        t.string('resource').notNullable();
+        t.integer('record_id').notNullable();
+        t.primary(['tag_id', 'resource', 'record_id']);
+        t.index(['resource', 'record_id']);
+    });
+    await db.schema.createTable('field_changes', (t) => {
+        t.bigIncrements('id');
+        t.bigInteger('activity_id')
+            .notNullable()
+            .references('id')
+            .inTable('activities')
+            .onDelete('CASCADE')
+            .index();
+        t.string('resource').notNullable();
+        t.integer('record_id').notNullable();
+        t.string('field').notNullable();
+        t.jsonb('before');
+        t.jsonb('after');
+        t.index(['resource', 'record_id', 'id']);
+    });
+}
+/** Work assigned to a user on a record; approval steps of workflows reuse it (phase 4). */
+export async function createAssignmentsSchema(db) {
+    await db.schema.createTable('assignments', (t) => {
+        t.bigIncrements('id');
+        t.string('resource').notNullable();
+        t.integer('record_id').notNullable();
+        t.integer('assignee_id').notNullable().references('id').inTable('users').onDelete('RESTRICT');
+        t.integer('assigned_by').references('id').inTable('users').onDelete('RESTRICT');
+        t.string('kind', 20).notNullable().defaultTo('task');
+        t.string('title', 200).notNullable();
+        t.text('note');
+        t.date('due_on');
+        t.string('status', 20).notNullable().defaultTo('open');
+        t.uuid('workflow_run_id');
+        t.string('workflow_step', 100);
+        t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.timestamp('completed_at', { useTz: true });
+        t.integer('completed_by').references('id').inTable('users').onDelete('RESTRICT');
+        t.string('outcome', 20);
+        t.index(['assignee_id', 'status', 'id']);
+        t.index(['resource', 'record_id']);
+        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.
+ */
+export async function createMessagingSchema(db) {
+    await db.schema.createTable('message_templates', (t) => {
+        t.string('key', 100).primary();
+        t.string('subject', 255).notNullable();
+        t.text('body').notNullable();
+        t.boolean('mail').notNullable().defaultTo(false);
+        t.integer('updated_by').references('id').inTable('users').onDelete('SET NULL');
+        t.timestamp('updated_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+    });
+    await db.schema.alterTable('notifications', (t) => {
+        t.string('template_key', 100);
+        t.string('mail_state', 20);
+        t.integer('mail_attempts').notNullable().defaultTo(0);
+        t.string('mail_error', 500);
+        t.timestamp('mailed_at', { useTz: true });
+    });
+    await db.raw("CREATE INDEX notifications_mail_pending ON notifications (id) WHERE mail_state = 'pending'");
+    await db.raw(`CREATE FUNCTION kit_notification_signal() RETURNS trigger LANGUAGE plpgsql AS $$ BEGIN PERFORM pg_notify('kit_notifications', json_build_object('userId', NEW.user_id, 'id', NEW.id)::text); RETURN NULL; END $$`);
+    await db.raw('CREATE TRIGGER kit_notification_signal AFTER INSERT ON notifications FOR EACH ROW EXECUTE FUNCTION kit_notification_signal()');
+}
+/** Outgoing webhooks and their delivery log (exactly one row per webhook and event). */
+export async function createWebhooksSchema(db) {
+    await db.schema.createTable('webhooks', (t) => {
+        t.increments('id');
+        t.string('name', 100).notNullable();
+        t.string('url', 2000).notNullable();
+        t.text('secret').notNullable();
+        t.jsonb('events').notNullable();
+        t.boolean('active').notNullable().defaultTo(true);
+        t.integer('failing').notNullable().defaultTo(0);
+        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_delivery_at', { useTz: true });
+    });
+    await db.raw('CREATE INDEX webhooks_events_gin ON webhooks USING gin(events)');
+    await db.schema.createTable('webhook_deliveries', (t) => {
+        t.uuid('id').primary();
+        t.integer('webhook_id').notNullable().references('id').inTable('webhooks').onDelete('CASCADE');
+        t.uuid('event_id').notNullable();
+        t.string('event').notNullable();
+        t.jsonb('payload').notNullable();
+        t.string('status', 20).notNullable().defaultTo('pending');
+        t.integer('attempts').notNullable().defaultTo(0);
+        t.integer('last_status');
+        t.string('last_error', 500);
+        t.timestamp('next_attempt_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.timestamp('delivered_at', { useTz: true });
+        t.unique(['webhook_id', 'event_id']);
+        t.index(['webhook_id', 'created_at']);
+    });
+    await db.raw("CREATE INDEX webhook_deliveries_due ON webhook_deliveries (next_attempt_at) WHERE status = 'pending'");
+}
+/** CSV import batches: parsed rows, column mapping, progress and per-row errors. */
+export async function createImportsSchema(db) {
+    await db.schema.createTable('import_batches', (t) => {
+        t.increments('id');
+        t.string('resource').notNullable();
+        t.integer('user_id').notNullable().references('id').inTable('users').onDelete('CASCADE');
+        t.string('file_name', 200).notNullable();
+        t.string('status', 20).notNullable();
+        t.jsonb('headers').notNullable();
+        t.jsonb('mapping').notNullable();
+        t.jsonb('rows').notNullable();
+        t.integer('total').notNullable();
+        t.integer('processed').notNullable().defaultTo(0);
+        t.integer('created').notNullable().defaultTo(0);
+        t.integer('failed').notNullable().defaultTo(0);
+        t.jsonb('errors').notNullable().defaultTo('[]');
+        t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.timestamp('started_at', { useTz: true });
+        t.timestamp('finished_at', { useTz: true });
+        t.index(['user_id', 'id']);
+        t.index(['status']);
+    });
+}
+/**
+ * Workflow engine state (phase 4): the submission envelope rows gain execution
+ * columns, and every transition is appended to workflow_events.
+ */
+export async function createWorkflowSchema(db) {
+    await db.schema.alterTable('workflow_runs', (t) => {
+        t.string('current_step', 100);
+        t.timestamp('wake_at', { useTz: true });
+        t.integer('attempts').notNullable().defaultTo(0);
+        t.string('last_error', 1000);
+        t.string('outcome', 30);
+        t.integer('started_by').references('id').inTable('users').onDelete('SET NULL');
+        t.timestamp('updated_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.timestamp('completed_at', { useTz: true });
+        t.index(['resource', 'record_id']);
+    });
+    await db.raw("CREATE INDEX workflow_runs_due ON workflow_runs (wake_at) WHERE status = 'running'");
+    await db.schema.createTable('workflow_events', (t) => {
+        t.bigIncrements('id');
+        t.uuid('run_id').notNullable().references('id').inTable('workflow_runs').onDelete('CASCADE');
+        t.string('step', 100);
+        t.string('event', 50).notNullable();
+        t.integer('actor_id').references('id').inTable('users').onDelete('SET NULL');
+        t.jsonb('detail').notNullable().defaultTo('{}');
+        t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        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/outbox.d.ts

@@ -6,6 +6,7 @@ export type DomainEvent = {
 };
 export type Listener = {
     name: string;
+    /** The exact event name, or '*' for a catch-all listener (for example webhooks). */
     event: string;
     handle(event: DomainEvent, trx: Knex.Transaction): Promise<void>;
 };

package/build/src/events/outbox.js

@@ -17,7 +17,7 @@ export async function publishOutbox(db, jobs, limit = 100) {
     });
 }
 export async function consumeEvent(db, listener, event) {
-    if (listener.event !== event.event)
+    if (listener.event !== '*' && listener.event !== event.event)
         return false;
     return db.transaction(async (trx) => {
         const inserted = await trx('processed_events')

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

@@ -1,5 +1,10 @@
 import type { Knex } from 'knex';
 import type { Action } from '../resource/types.js';
+export type FieldChange = {
+    field: string;
+    before: unknown;
+    after: unknown;
+};
 /** Infrastructure writes for a module-owned mutation, inside its existing transaction. */
 export declare function recordMutation(trx: Knex.Transaction, mutation: {
     module: string;
@@ -10,4 +15,10 @@ export declare function recordMutation(trx: Knex.Transaction, mutation: {
     impersonatorId?: number;
     action: Action;
     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

@@ -19,7 +19,8 @@ export async function recordMutation(trx, mutation) {
         actorId: mutation.actorId,
         ...(mutation.impersonatorId ? { impersonatorId: mutation.impersonatorId } : {}),
     };
-    await trx('activities').insert({
+    const [activity] = await trx('activities')
+        .insert({
         resource: mutation.resource,
         record_id: mutation.id,
         actor_id: mutation.actorId,
@@ -27,8 +28,20 @@ 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');
+    if (mutation.changes?.length)
+        await trx('field_changes').insert(mutation.changes.map((change) => ({
+            activity_id: activity.id,
+            resource: mutation.resource,
+            record_id: mutation.id,
+            field: change.field,
+            before: JSON.stringify(change.before ?? null),
+            after: JSON.stringify(change.after ?? null),
+        })));
     await trx('outbox').insert({
         id: eventId,
         event,