@adula/kit 1.0.0 → 1.2.0

package/build/src/attachments/attachment_service.d.ts

@@ -38,6 +38,18 @@ export type UploadInput = {
     orgUnitId?: number | null;
     resource?: string | null;
     field?: string | null;
+    /**
+     * The redeemed upload grant that authorized this upload instead of a role rule. The upload
+     * takes the grant's resource, field and unit, can bind to the granted record only, and is
+     * recorded in that record's activity log.
+     */
+    grant?: {
+        id: number;
+        resource: string;
+        recordId: number;
+        field: string;
+        orgUnitId: number | null;
+    } | null;
 };
 export type ClaimInput = {
     attachmentId: number;

package/build/src/attachments/attachment_service.js

@@ -1,5 +1,6 @@
 import { KitError } from '../admin/errors.js';
 import { identifier } from '../resource/define_resource.js';
+import { logActivity } from '../core/activity.js';
 const MAX_ID = 2147483647;
 const REJECTED = 'المرفق غير موجود أو لا يخصك';
 /** Business documents, images and archives; a field widens or narrows it with `accept`. */
@@ -151,6 +152,18 @@ export async function registerUpload(db, input) {
     }
     if (input.resource)
         identifier(input.resource);
+    const grant = input.grant;
+    if (grant &&
+        (!isAttachmentId(grant.id) ||
+            !isAttachmentId(grant.recordId) ||
+            grant.resource !== input.resource ||
+            grant.field !== input.field))
+        throw new KitError(422, 'E_ATTACHMENT_INPUT', 'The upload grant names another field');
+    // Only a redeemed grant may mark an upload as granted.
+    const data = { ...input.data };
+    delete data.uploadGrant;
+    if (grant)
+        data.uploadGrant = { id: grant.id, recordId: grant.recordId };
     const [row] = await db('attachments')
         .insert({
         disk: input.disk,
@@ -160,13 +173,21 @@ export async function registerUpload(db, input) {
         size: input.size,
         mime_type: input.mimeType || 'application/octet-stream',
         extname: input.extname,
-        data: JSON.stringify(input.data),
+        data: JSON.stringify(data),
         uploaded_by: input.uploadedBy,
-        org_unit_id: input.orgUnitId ?? null,
+        org_unit_id: grant ? grant.orgUnitId : (input.orgUnitId ?? null),
         resource: input.resource ?? null,
         field: input.field ?? null,
     })
         .returning('*');
+    if (grant)
+        await logActivity(db, {
+            resource: grant.resource,
+            recordId: grant.recordId,
+            actorId: input.uploadedBy,
+            action: 'upload_via_grant',
+            changes: { field: grant.field, attachmentId: Number(row.id), grantId: grant.id },
+        });
     return fromRow(row);
 }
 export async function findAttachment(db, id) {
@@ -203,6 +224,11 @@ export async function claimAttachment(trx, input) {
     if ((row.resource !== null && row.resource !== input.resource) ||
         (row.field !== null && row.field !== input.field))
         throw new KitError(422, 'E_ATTACHMENT', 'المرفق مخصص لحقل آخر');
+    // An upload authorized by a grant binds to the granted record only, never to a new one.
+    const granted = row.data?.uploadGrant;
+    if (granted &&
+        (input.recordId === undefined || Number(granted.recordId) !== Number(input.recordId)))
+        throw new KitError(422, 'E_ATTACHMENT', 'المرفق مخصص لسجل آخر');
     const bound = row.record_id !== null;
     const sameRecord = bound &&
         input.recordId !== undefined &&

package/build/src/attachments/upload_grants.d.ts

@@ -0,0 +1,44 @@
+import type { Knex } from 'knex';
+import type { ResourceRegistry } from '../resource/registry.js';
+/** Longest lifetime of an upload grant; module pages ask for one right before the upload. */
+export declare const UPLOAD_GRANT_MAX_TTL_MS: number;
+export type UploadGrantInput = {
+    resource: string;
+    recordId: number;
+    /** An attachment field of the resource. */
+    field: string;
+    /** The user who may upload with the grant. */
+    userId: number;
+    /** Who decided the grant (the module's signed-in user or a system actor); defaults to userId. */
+    actorId?: number;
+    /** Lifetime in milliseconds, at most one hour (default ten minutes). */
+    ttlMs?: number;
+};
+export type UploadGrant = {
+    token: string;
+    expiresAt: string;
+};
+export type RedeemedUploadGrant = {
+    id: number;
+    resource: string;
+    recordId: number;
+    field: string;
+    orgUnitId: number | null;
+};
+/**
+ * Lets one user upload a file for one attachment field of one existing record, when module
+ * code has authorized that user itself (for example the inspector of a visit) and the role
+ * rules grant no generic right. Only the token hash is stored. The grant replaces the
+ * upload's authorization (the role rule, the field's permission and hidden levels and form
+ * membership); type, size, the pending-upload limit, ownership and binding through the
+ * record write stay as for any upload, and the upload can bind to this record only. Issuing it is recorded in the record's activity log. Call it from module code after
+ * the module's own authorization, never on a user's word alone.
+ */
+export declare function grantUpload(db: Knex, registry: Pick<ResourceRegistry, 'all' | 'get'>, input: UploadGrantInput): Promise<UploadGrant>;
+/**
+ * The grant a token names, while it is unexpired, held by this user, and its record is still
+ * live and, for documents, a draft; otherwise null. The unit is the record's current unit.
+ */
+export declare function redeemUploadGrant(db: Knex, registry: Pick<ResourceRegistry, 'all' | 'get'>, token: unknown, userId: number): Promise<RedeemedUploadGrant | null>;
+/** Removes expired grants; the upload pruning schedule may call it. */
+export declare function pruneUploadGrants(db: Knex): Promise<number>;

package/build/src/attachments/upload_grants.js

@@ -0,0 +1,105 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { KitError } from '../admin/errors.js';
+import { logActivity } from '../core/activity.js';
+import { isAttachmentId } from './attachment_service.js';
+/** Longest lifetime of an upload grant; module pages ask for one right before the upload. */
+export const UPLOAD_GRANT_MAX_TTL_MS = 60 * 60 * 1000;
+const DEFAULT_TTL_MS = 10 * 60 * 1000;
+const hash = (token) => createHash('sha256').update(token).digest('hex');
+/**
+ * Lets one user upload a file for one attachment field of one existing record, when module
+ * code has authorized that user itself (for example the inspector of a visit) and the role
+ * rules grant no generic right. Only the token hash is stored. The grant replaces the
+ * upload's authorization (the role rule, the field's permission and hidden levels and form
+ * membership); type, size, the pending-upload limit, ownership and binding through the
+ * record write stay as for any upload, and the upload can bind to this record only. Issuing it is recorded in the record's activity log. Call it from module code after
+ * the module's own authorization, never on a user's word alone.
+ */
+export async function grantUpload(db, registry, input) {
+    if (typeof input.resource !== 'string' ||
+        !registry.all().some((entry) => entry.name === input.resource))
+        throw new KitError(404, 'E_NOT_FOUND', 'الكيان غير موجود');
+    const resource = registry.get(input.resource);
+    const field = Object.hasOwn(resource.fields, input.field) ? resource.fields[input.field] : null;
+    if (!field || field.type !== 'attachment')
+        throw new KitError(422, 'E_FIELD_INVALID', 'الحقل ليس حقل مرفقات');
+    if (!isAttachmentId(input.recordId) || !isAttachmentId(input.userId))
+        throw new KitError(422, 'E_UPLOAD_GRANT', 'Invalid record or user');
+    if (input.actorId !== undefined && !isAttachmentId(input.actorId))
+        throw new KitError(422, 'E_UPLOAD_GRANT', 'Invalid actor');
+    const ttl = input.ttlMs ?? DEFAULT_TTL_MS;
+    if (!Number.isSafeInteger(ttl) || ttl < 1000 || ttl > UPLOAD_GRANT_MAX_TTL_MS)
+        throw new KitError(422, 'E_UPLOAD_GRANT', 'Grant lifetime must be between 1 second and 1 hour');
+    const record = await db(resource.name)
+        .where('id', input.recordId)
+        .whereNull('deleted_at')
+        .first([
+        'id',
+        ...(resource.scoped ? ['org_unit_id'] : []),
+        ...(resource.submittable ? ['doc_status'] : []),
+    ]);
+    if (!record)
+        throw new KitError(404, 'E_NOT_FOUND', 'السجل غير موجود');
+    // A submitted or cancelled document is locked: no new evidence can be bound to it.
+    if (resource.submittable && Number(record.doc_status) !== 0)
+        throw new KitError(409, 'E_DOCUMENT_LOCKED', 'المستند معتمد أو ملغى ولا يقبل مرفقات جديدة');
+    // A disabled user cannot sign in, so cannot redeem the grant either.
+    if (!(await db('users').where('id', input.userId).first('id')))
+        throw new KitError(422, 'E_UPLOAD_GRANT', 'Unknown user');
+    const token = randomBytes(32).toString('base64url');
+    const expiresAt = new Date(Date.now() + ttl);
+    await db('upload_grants').insert({
+        token_hash: hash(token),
+        user_id: input.userId,
+        resource: resource.name,
+        record_id: input.recordId,
+        field: input.field,
+        org_unit_id: resource.scoped ? record.org_unit_id : null,
+        expires_at: expiresAt,
+        created_by: input.actorId ?? input.userId,
+    });
+    await logActivity(db, {
+        resource: resource.name,
+        recordId: input.recordId,
+        actorId: input.actorId ?? input.userId,
+        action: 'upload_granted',
+        changes: { field: input.field, userId: input.userId, expiresAt: expiresAt.toISOString() },
+    });
+    return { token, expiresAt: expiresAt.toISOString() };
+}
+/**
+ * The grant a token names, while it is unexpired, held by this user, and its record is still
+ * live and, for documents, a draft; otherwise null. The unit is the record's current unit.
+ */
+export async function redeemUploadGrant(db, registry, token, userId) {
+    if (typeof token !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(token))
+        return null;
+    const row = await db('upload_grants')
+        .where({ token_hash: hash(token), user_id: userId })
+        .where('expires_at', '>', db.fn.now())
+        .first();
+    if (!row || !registry.all().some((entry) => entry.name === row.resource))
+        return null;
+    const resource = registry.get(String(row.resource));
+    const record = await db(resource.name)
+        .where('id', row.record_id)
+        .whereNull('deleted_at')
+        .first([
+        'id',
+        ...(resource.scoped ? ['org_unit_id'] : []),
+        ...(resource.submittable ? ['doc_status'] : []),
+    ]);
+    if (!record || (resource.submittable && Number(record.doc_status) !== 0))
+        return null;
+    return {
+        id: Number(row.id),
+        resource: resource.name,
+        recordId: Number(row.record_id),
+        field: String(row.field),
+        orgUnitId: resource.scoped && record.org_unit_id !== null ? Number(record.org_unit_id) : null,
+    };
+}
+/** Removes expired grants; the upload pruning schedule may call it. */
+export async function pruneUploadGrants(db) {
+    return db('upload_grants').where('expires_at', '<=', db.fn.now()).delete();
+}

package/build/src/auth/ability.d.ts

@@ -17,7 +17,7 @@ export type Actor = {
     impersonatorId?: number;
 };
 export type KitAbility = Ability<[string, any], Conditions>;
-export declare const abilitySchemas: WeakMap<KitAbility, readonly Pick<Resource, "fields" | "name">[]>;
+export declare const abilitySchemas: WeakMap<KitAbility, readonly Pick<Resource, "name" | "fields">[]>;
 export declare function buildAbility(rules: readonly Rule[], schemas?: readonly Pick<Resource, 'name' | 'fields'>[]): KitAbility;
 export declare function inOrgScope(path: unknown, paths: readonly string[]): boolean;
 export declare function canRecord(ability: KitAbility, actor: Actor, resource: Resource, action: string, record: RecordData, field?: string): boolean;

package/build/src/auth/ability.js

@@ -1,9 +1,12 @@
 import { Ability, subject, fieldPatternMatcher } from '@casl/ability';
-import { conditionsMatcher, predicates } from './conditions.js';
+import { conditionsMatcher, predicates, usesActor } from './conditions.js';
 export const abilitySchemas = new WeakMap();
 export function buildAbility(rules, schemas = []) {
     for (const rule of rules) {
         predicates(rule.conditions);
+        // An unresolved placeholder would compare as text: `$ne` and inverted rules would fail open.
+        if (usesActor(rule.conditions))
+            throw new Error('Rule conditions use $actor.id; resolve them with resolveActorConditions');
         if (rule.fields?.length === 0)
             throw new Error('An empty fields rule is invalid');
     }

package/build/src/auth/actor_store.js

@@ -1,3 +1,4 @@
+import { actorConditionField, resolveActorConditions } from './conditions.js';
 export class ActorStore {
     db;
     registry;
@@ -30,10 +31,14 @@ export class ActorStore {
             // Privileged field access only comes from deployment-wide roles.
             if (!row.role_path)
                 permissionLevel = Math.max(permissionLevel, row.permission_level);
+            const subject = this.registry.all().find((resource) => resource.name === row.subject);
             const rule = {
                 subject: row.subject,
                 action: row.action,
-                conditions: row.conditions ?? undefined,
+                // "$actor.id" becomes this user's id, so CASL and SQL compare a bound integer.
+                // On another field of a registered resource it stays, and buildAbility refuses the
+                // rule (fail closed). A store built without that resource cannot judge its fields.
+                conditions: resolveActorConditions(row.conditions ?? undefined, id, (field) => subject ? actorConditionField(subject, field) : true),
                 fields: row.fields ?? undefined,
                 inverted: row.inverted,
             };

package/build/src/auth/conditions.d.ts

@@ -6,6 +6,21 @@ export type Predicate = {
     operator: Operator;
     value: Scalar | Scalar[];
 };
+/**
+ * Role rule operand replaced by the signed-in user's id when the actor is loaded
+ * (for example `{ createdBy: '$actor.id' }`). It is bound as a query parameter.
+ */
+export declare const ACTOR_ID = "$actor.id";
+/**
+ * Replaces ACTOR_ID operands with the actor's id; other values are returned unchanged.
+ * With `accepts`, only the fields it accepts are resolved: a placeholder left on another
+ * field makes buildAbility refuse the rule instead of comparing an id with text.
+ */
+export declare function resolveActorConditions(conditions: Conditions | undefined, actorId: number, accepts?: (field: string) => boolean): Conditions | undefined;
+/** Fields whose conditions may name the current user: user fields, createdBy and updatedBy. */
+export declare function actorConditionField(resource: Pick<Resource, 'fields'> | undefined, field: string): boolean;
+/** Whether a condition object uses the ACTOR_ID placeholder as an operand. */
+export declare function usesActor(conditions: Conditions | undefined | null): boolean;
 export declare function predicates(conditions?: Conditions, fields?: Set<string>): Predicate[];
 export declare function likePattern(value: string): RegExp;
 export declare function conditionsMatcher(conditions: Conditions, schemas?: readonly Pick<Resource, 'name' | 'fields'>[]): (record: RecordData) => boolean;

package/build/src/auth/conditions.js

@@ -1,4 +1,40 @@
 import { columnName } from '../resource/define_resource.js';
+/**
+ * Role rule operand replaced by the signed-in user's id when the actor is loaded
+ * (for example `{ createdBy: '$actor.id' }`). It is bound as a query parameter.
+ */
+export const ACTOR_ID = '$actor.id';
+/**
+ * Replaces ACTOR_ID operands with the actor's id; other values are returned unchanged.
+ * With `accepts`, only the fields it accepts are resolved: a placeholder left on another
+ * field makes buildAbility refuse the rule instead of comparing an id with text.
+ */
+export function resolveActorConditions(conditions, actorId, accepts) {
+    if (!conditions || typeof conditions !== 'object' || Array.isArray(conditions))
+        return conditions;
+    const resolve = (value) => value === ACTOR_ID ? actorId : Array.isArray(value) ? value.map(resolve) : value;
+    return Object.fromEntries(Object.entries(conditions).map(([field, condition]) => [
+        field,
+        accepts && !accepts(field)
+            ? condition
+            : condition !== null && typeof condition === 'object' && !Array.isArray(condition)
+                ? Object.fromEntries(Object.entries(condition).map(([operator, value]) => [operator, resolve(value)]))
+                : resolve(condition),
+    ]));
+}
+/** Fields whose conditions may name the current user: user fields, createdBy and updatedBy. */
+export function actorConditionField(resource, field) {
+    return (resource !== undefined &&
+        (field === 'createdBy' || field === 'updatedBy' || resource.fields[field]?.type === 'user'));
+}
+/** Whether a condition object uses the ACTOR_ID placeholder as an operand. */
+export function usesActor(conditions) {
+    const found = (value) => value === ACTOR_ID ||
+        (Array.isArray(value)
+            ? value.some(found)
+            : value !== null && typeof value === 'object' && Object.values(value).some(found));
+    return found(conditions ?? {});
+}
 const operators = new Set(['$eq', '$ne', '$in', '$lt', '$gt', '$like']);
 const scalar = (v) => v === null ||
     ['string', 'boolean'].includes(typeof v) ||

package/build/src/auth/sql.js

@@ -1,5 +1,5 @@
 import { abilitySchemas } from './ability.js';
-import { predicates } from './conditions.js';
+import { predicates, usesActor } from './conditions.js';
 import { columnName } from '../resource/define_resource.js';
 import { canonicalDate, canonicalMoney } from '../resource/values.js';
 export function conditionSql(conditions, resource) {
@@ -14,6 +14,9 @@ export function conditionSql(conditions, resource) {
         'orgPath',
     ]);
     const parts = predicates(conditions, allowed);
+    // The current user is bound as an integer; an unresolved placeholder must not reach SQL.
+    if (usesActor(conditions))
+        throw new Error('Rule conditions use $actor.id; resolve them with resolveActorConditions');
     const bindings = [];
     const text = parts
         .map(({ field, operator, value }) => {
@@ -25,7 +28,8 @@ export function conditionSql(conditions, resource) {
             throw new Error(`Conditions on ${type} fields require a typed adapter`);
         const expected = ['id', 'orgUnitId', 'createdBy', 'updatedBy', 'version', 'docStatus'].includes(field) ||
             type === 'integer' ||
-            type === 'belongsTo'
+            type === 'belongsTo' ||
+            type === 'user'
             ? 'number'
             : type === 'boolean'
                 ? 'boolean'

package/build/src/collaboration/assignments.d.ts

@@ -8,6 +8,8 @@ export type Assignment = {
     resource: string;
     resourceLabel: string;
     recordId: number;
+    /** The record's title under the viewer's field access; null shows the id instead (#32). */
+    recordTitle: string | null;
     assigneeId: number;
     assigneeName: string | null;
     assignedBy: number | null;
@@ -22,13 +24,33 @@ export type Assignment = {
     completedAt: string | null;
     /** Set for approval steps; completion goes through the workflow engine instead. */
     workflowRunId: string | null;
+    /** Opened and closed by module code with the record's state; a manual close needs a note. */
+    managed: boolean;
+    /** Whether closing this task by hand needs a note. */
+    closeNote: CloseNotePolicy;
+    /** The note written when the task was closed, by hand or by module code. */
+    closeReason: string | null;
     canComplete: boolean;
     canCancel: boolean;
+    /** An open approval step waiting for this user's decision (WorkflowEngine.decide). 1.2; optional for compatibility. */
+    canDecide?: boolean;
 };
 export type AssignmentPage = {
     data: Assignment[];
     nextCursor: string | null;
+    /** Open items of every kind. */
     open: number;
+    /** Open approval steps among them. 1.2; optional for compatibility. */
+    approvals?: number;
+};
+/**
+ * Whether closing a task by hand needs a note. Each application chooses: `optional`
+ * (the default) shows the note field but accepts it empty; `required` refuses an empty
+ * note. Managed tasks always need a note when closed by hand.
+ */
+export type CloseNotePolicy = 'optional' | 'required';
+export type AssignmentOptions = {
+    closeNote?: CloseNotePolicy;
 };
 /**
  * Assignments put a record on someone's "my tasks" list. Assigning needs update
@@ -39,7 +61,8 @@ export declare class Assignments {
     private db;
     private resources;
     private actors;
-    constructor(db: Knex, resources: ResourceService, actors: ActorLoader);
+    private options;
+    constructor(db: Knex, resources: ResourceService, actors: ActorLoader, options?: AssignmentOptions);
     forRecord(name: string, id: number, actor: Actor): Promise<Assignment[]>;
     assign(name: string, id: number, actor: Actor, input: {
         assigneeId: unknown;
@@ -62,17 +85,45 @@ export declare class Assignments {
         kind?: string;
         workflowRunId?: string;
         workflowStep?: string;
+        /**
+         * The task represents open work on the record, such as a ticket to resolve. The
+         * assignee cannot mark it done; module code closes it with close() (#51).
+         */
+        managed?: boolean;
     }): Promise<any>;
     /** The signed-in user's own tasks, open first; records they can no longer read are hidden. */
     mine(actor: Actor, options?: {
         status?: string;
+        /** approval: workflow decisions only; task: manual assignments only. */
+        kind?: string;
         cursor?: string;
         limit?: number;
     }): Promise<AssignmentPage>;
-    /** The assignee marks the task done, or the assigner cancels it. */
-    complete(assignmentId: unknown, actor: Actor, outcome?: 'done' | 'cancelled'): Promise<void>;
+    /**
+     * The assignee marks the task done, or the assigner cancels it, with a closing note. The
+     * note is required when the application's policy says so and for managed tasks.
+     */
+    complete(assignmentId: unknown, actor: Actor, outcome?: 'done' | 'cancelled', input?: {
+        note?: unknown;
+    }): Promise<void>;
+    /**
+     * Closes the open managed tasks of a record when module code decides that its work is
+     * finished (or no longer needed), for example from a listener on the record's final
+     * state. Recorded in the record's activity log with the reason; the assigner (done) or
+     * the assignee (cancelled) is notified as for a manual close. Returns the closed count.
+     */
+    close(resource: string, recordId: number, options: {
+        /** The user recorded as closing the tasks, usually the author of the final change. */
+        actorId: number;
+        outcome?: 'done' | 'cancelled';
+        reason?: string;
+        trx?: Knex.Transaction;
+    }): Promise<number>;
     private query;
     private present;
+    /** Adds record titles in one read per resource, under the viewer's field access. */
+    private titled;
+    private closeNote;
     private label;
     private canView;
 }