@adula/kit 0.2.0-alpha.1

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

@@ -0,0 +1,71 @@
+import type { Knex } from 'knex';
+import type { JsonValue } from '../resource/types.js';
+export type AttachmentSummary = {
+    id: number;
+    name: string;
+    size: number;
+    mimeType: string;
+    url: string;
+};
+export type AttachmentRecord = {
+    id: number;
+    disk: string;
+    path: string;
+    name: string;
+    originalName: string;
+    size: number;
+    mimeType: string;
+    extname: string;
+    data: Record<string, JsonValue>;
+    uploadedBy: number;
+    orgUnitId: number | null;
+    resource: string | null;
+    recordId: number | null;
+    field: string | null;
+    createdAt: string;
+    deletedAt: string | null;
+};
+export type UploadInput = {
+    disk: string;
+    path: string;
+    name: string;
+    originalName: string;
+    size: number;
+    mimeType: string;
+    extname: string;
+    data: Record<string, unknown>;
+    uploadedBy: number;
+    orgUnitId?: number | null;
+    resource?: string | null;
+    field?: string | null;
+};
+export type ClaimInput = {
+    attachmentId: number;
+    actor: {
+        id: number;
+    };
+    resource: string;
+    field: string;
+    /** Omitted while a record is being created: the upload is verified but not bound yet. */
+    recordId?: number;
+    orgUnitId?: number | null;
+    scoped: boolean;
+};
+export declare function attachmentUrl(id: number): string;
+export declare function isAttachmentId(value: unknown): value is number;
+/** Disk keys stay relative and slash-separated so files move between disks unchanged. */
+export declare function isRelativeDiskPath(path: unknown): path is string;
+export declare function summarizeAttachment(row: Record<string, unknown>): AttachmentSummary;
+/** Records a stored file. The host performs the Drive write; the kit only keeps verified metadata. */
+export declare function registerUpload(db: Knex, input: UploadInput): Promise<AttachmentRecord>;
+export declare function findAttachment(db: Knex, id: unknown): Promise<AttachmentRecord | undefined>;
+/** One query per resource page: callers collect every attachment id first. */
+export declare function loadAttachments(db: Knex, ids: readonly number[]): Promise<Map<number, AttachmentSummary>>;
+/**
+ * Ownership is decided inside the caller's transaction: a rejected claim rolls
+ * the whole record write back. Only the uploader may bind an upload, and an
+ * upload binds to exactly one record field.
+ */
+export declare function claimAttachment(trx: Knex.Transaction, input: ClaimInput): Promise<AttachmentRecord>;
+/** Unbinding keeps the file and its metadata for restore drills; only the row is soft-deleted. */
+export declare function releaseAttachment(db: Knex, id: number): Promise<boolean>;

package/build/src/attachments/attachment_service.js

@@ -0,0 +1,182 @@
+import { KitError } from '../admin/errors.js';
+import { identifier } from '../resource/define_resource.js';
+const MAX_ID = 2147483647;
+const REJECTED = 'المرفق غير موجود أو لا يخصك';
+export function attachmentUrl(id) {
+    return `/attachments/${id}`;
+}
+export function isAttachmentId(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 1 && Number(value) <= MAX_ID;
+}
+/** Disk keys stay relative and slash-separated so files move between disks unchanged. */
+export function isRelativeDiskPath(path) {
+    return (typeof path === 'string' &&
+        path.length > 0 &&
+        path.length <= 1024 &&
+        !path.startsWith('/') &&
+        !path.includes('\\') &&
+        !path.includes('\0') &&
+        !/^[a-zA-Z]:/.test(path) &&
+        path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..'));
+}
+function text(value, max) {
+    return (typeof value === 'string' && value.length > 0 && value.length <= max && !value.includes('\0'));
+}
+export function summarizeAttachment(row) {
+    return {
+        id: Number(row.id),
+        name: String(row.original_name),
+        size: Number(row.size),
+        mimeType: String(row.mime_type),
+        url: attachmentUrl(Number(row.id)),
+    };
+}
+function fromRow(row) {
+    const stamp = (value) => (value instanceof Date ? value.toISOString() : value);
+    return {
+        id: Number(row.id),
+        disk: String(row.disk),
+        path: String(row.path),
+        name: String(row.name),
+        originalName: String(row.original_name),
+        size: Number(row.size),
+        mimeType: String(row.mime_type),
+        extname: String(row.extname),
+        data: (row.data ?? {}),
+        uploadedBy: Number(row.uploaded_by),
+        orgUnitId: row.org_unit_id === null || row.org_unit_id === undefined ? null : Number(row.org_unit_id),
+        resource: row.resource === null || row.resource === undefined ? null : String(row.resource),
+        recordId: row.record_id === null || row.record_id === undefined ? null : Number(row.record_id),
+        field: row.field === null || row.field === undefined ? null : String(row.field),
+        createdAt: String(stamp(row.created_at)),
+        deletedAt: row.deleted_at === null || row.deleted_at === undefined
+            ? null
+            : String(stamp(row.deleted_at)),
+    };
+}
+/** Records a stored file. The host performs the Drive write; the kit only keeps verified metadata. */
+export async function registerUpload(db, input) {
+    if (!text(input.disk, 100) || !/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(input.disk))
+        throw new KitError(422, 'E_ATTACHMENT_INPUT', 'Invalid disk name');
+    if (!isRelativeDiskPath(input.path))
+        throw new KitError(422, 'E_ATTACHMENT_INPUT', 'Attachment paths must be relative disk keys');
+    if (!text(input.name, 255) ||
+        input.name.includes('/') ||
+        input.name !== input.path.split('/').at(-1))
+        throw new KitError(422, 'E_ATTACHMENT_INPUT', 'Attachment name must be the last path segment');
+    if (!text(input.originalName, 255) || /[/\\]/.test(input.originalName))
+        throw new KitError(422, 'E_ATTACHMENT_INPUT', 'Invalid original file name');
+    if (!Number.isSafeInteger(input.size) || input.size < 0)
+        throw new KitError(422, 'E_ATTACHMENT_INPUT', 'Invalid file size');
+    if (typeof input.mimeType !== 'string' ||
+        input.mimeType.length > 255 ||
+        /[\r\n\0]/.test(input.mimeType))
+        throw new KitError(422, 'E_ATTACHMENT_INPUT', 'Invalid content type');
+    if (typeof input.extname !== 'string' || !/^[a-z0-9]{0,32}$/.test(input.extname))
+        throw new KitError(422, 'E_ATTACHMENT_INPUT', 'Invalid file extension');
+    if (!input.data || typeof input.data !== 'object' || Array.isArray(input.data))
+        throw new KitError(422, 'E_ATTACHMENT_INPUT', 'Attachment data must be an object');
+    if (!isAttachmentId(input.uploadedBy))
+        throw new KitError(422, 'E_ATTACHMENT_INPUT', 'Invalid uploader');
+    if (input.orgUnitId !== undefined && input.orgUnitId !== null && !isAttachmentId(input.orgUnitId))
+        throw new KitError(422, 'E_ATTACHMENT_INPUT', 'Invalid organization unit');
+    for (const key of ['resource', 'field']) {
+        const value = input[key];
+        if (value !== undefined &&
+            value !== null &&
+            (typeof value !== 'string' || !/^[a-zA-Z][a-zA-Z0-9_]*$/.test(value)))
+            throw new KitError(422, 'E_ATTACHMENT_INPUT', `Invalid ${key}`);
+    }
+    if (input.resource)
+        identifier(input.resource);
+    const [row] = await db('attachments')
+        .insert({
+        disk: input.disk,
+        path: input.path,
+        name: input.name,
+        original_name: input.originalName,
+        size: input.size,
+        mime_type: input.mimeType || 'application/octet-stream',
+        extname: input.extname,
+        data: JSON.stringify(input.data),
+        uploaded_by: input.uploadedBy,
+        org_unit_id: input.orgUnitId ?? null,
+        resource: input.resource ?? null,
+        field: input.field ?? null,
+    })
+        .returning('*');
+    return fromRow(row);
+}
+export async function findAttachment(db, id) {
+    if (!isAttachmentId(id))
+        return undefined;
+    const row = await db('attachments').where('id', id).whereNull('deleted_at').first();
+    return row ? fromRow(row) : undefined;
+}
+/** One query per resource page: callers collect every attachment id first. */
+export async function loadAttachments(db, ids) {
+    const summaries = new Map();
+    const valid = [...new Set(ids.filter(isAttachmentId))];
+    if (!valid.length)
+        return summaries;
+    const rows = await db('attachments')
+        .whereIn('id', valid)
+        .whereNull('deleted_at')
+        .select('id', 'original_name', 'size', 'mime_type');
+    for (const row of rows)
+        summaries.set(Number(row.id), summarizeAttachment(row));
+    return summaries;
+}
+/**
+ * Ownership is decided inside the caller's transaction: a rejected claim rolls
+ * the whole record write back. Only the uploader may bind an upload, and an
+ * upload binds to exactly one record field.
+ */
+export async function claimAttachment(trx, input) {
+    if (!isAttachmentId(input.attachmentId))
+        throw new KitError(422, 'E_ATTACHMENT', REJECTED);
+    const row = await trx('attachments').where('id', input.attachmentId).forUpdate().first();
+    if (!row || row.deleted_at !== null || Number(row.uploaded_by) !== Number(input.actor.id))
+        throw new KitError(422, 'E_ATTACHMENT', REJECTED);
+    if ((row.resource !== null && row.resource !== input.resource) ||
+        (row.field !== null && row.field !== input.field))
+        throw new KitError(422, 'E_ATTACHMENT', 'المرفق مخصص لحقل آخر');
+    const bound = row.record_id !== null;
+    const sameRecord = bound &&
+        input.recordId !== undefined &&
+        Number(row.record_id) === Number(input.recordId) &&
+        row.resource === input.resource &&
+        row.field === input.field;
+    if (bound && !sameRecord)
+        throw new KitError(422, 'E_ATTACHMENT', 'المرفق مرتبط بسجل آخر');
+    const orgUnitId = input.scoped && input.orgUnitId !== undefined && input.orgUnitId !== null
+        ? Number(input.orgUnitId)
+        : null;
+    if (input.scoped &&
+        !sameRecord &&
+        row.org_unit_id !== null &&
+        (orgUnitId === null || Number(row.org_unit_id) !== orgUnitId))
+        throw new KitError(422, 'E_ATTACHMENT', 'المرفق يتبع وحدة تنظيمية أخرى');
+    if (input.recordId === undefined)
+        return fromRow(row);
+    const [updated] = await trx('attachments')
+        .where('id', input.attachmentId)
+        .update({
+        resource: input.resource,
+        field: input.field,
+        record_id: input.recordId,
+        org_unit_id: input.scoped ? orgUnitId : row.org_unit_id,
+    })
+        .returning('*');
+    return fromRow(updated);
+}
+/** Unbinding keeps the file and its metadata for restore drills; only the row is soft-deleted. */
+export async function releaseAttachment(db, id) {
+    if (!isAttachmentId(id))
+        return false;
+    const changed = await db('attachments')
+        .where('id', id)
+        .whereNull('deleted_at')
+        .update({ deleted_at: db.fn.now() });
+    return changed > 0;
+}

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

@@ -0,0 +1,4 @@
+import type { Knex } from 'knex';
+import type { Finding } from '../commands/doctor.js';
+/** Unbound uploads are files whose form was never saved; they are reported, never deleted here. */
+export declare function diagnoseAttachments(db: Knex, now?: number): Promise<Finding>;

package/build/src/attachments/doctor.js

@@ -0,0 +1,28 @@
+const STALE_UPLOAD_MS = 24 * 3600000;
+/** Unbound uploads are files whose form was never saved; they are reported, never deleted here. */
+export async function diagnoseAttachments(db, now = Date.now()) {
+    try {
+        const result = await db.raw(`SELECT
+         count(*) FILTER (WHERE record_id IS NOT NULL) AS bound,
+         count(*) FILTER (WHERE record_id IS NULL) AS unbound,
+         count(*) FILTER (WHERE record_id IS NULL AND created_at < ?) AS stale,
+         coalesce(sum(size), 0) AS bytes
+       FROM attachments WHERE deleted_at IS NULL`, [new Date(now - STALE_UPLOAD_MS).toISOString()]);
+        const row = result.rows[0];
+        const live = Number(row.bound) + Number(row.unbound);
+        return {
+            check: 'attachments',
+            status: 'info',
+            message: `${row.bound} bound attachments, ${row.unbound} unbound uploads (${row.stale} older than 24 hours), ${row.bytes} bytes in ${live} live files`,
+        };
+    }
+    catch (error) {
+        if (error.code === '42P01')
+            return {
+                check: 'attachments',
+                status: 'warn',
+                message: 'attachments table is missing; run migration:run',
+            };
+        throw error;
+    }
+}

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

@@ -0,0 +1,39 @@
+import type { Readable } from 'node:stream';
+import type { Knex } from 'knex';
+/** The subset of a Drive disk the migration needs; keeps the kit independent of flydrive. */
+export type StorageDisk = {
+    exists(key: string): Promise<boolean>;
+    getStream(key: string): Promise<Readable>;
+    putStream(key: string, contents: Readable): Promise<void>;
+    getMetaData(key: string): Promise<{
+        contentLength: number;
+    }>;
+};
+export type StorageMigrationOptions = {
+    from: string;
+    to: string;
+    disks: readonly string[];
+    use: (name: string) => StorageDisk;
+    dryRun?: boolean;
+    report?: (line: string) => void;
+};
+export type StorageMigrationResult = {
+    from: string;
+    to: string;
+    dryRun: boolean;
+    total: number;
+    copied: number;
+    skipped: number;
+    failed: {
+        id: number;
+        path: string;
+        reason: string;
+    }[];
+    remaining: number;
+};
+/**
+ * Copies every live attachment file to the target disk, verifies its size and
+ * repoints the row in its own statement. Rerunning after an interruption only
+ * touches rows still on the source disk; source files are never deleted here.
+ */
+export declare function migrateStorage(db: Knex, options: StorageMigrationOptions): Promise<StorageMigrationResult>;

package/build/src/attachments/storage_migrate.js

@@ -0,0 +1,64 @@
+/**
+ * Copies every live attachment file to the target disk, verifies its size and
+ * repoints the row in its own statement. Rerunning after an interruption only
+ * touches rows still on the source disk; source files are never deleted here.
+ */
+export async function migrateStorage(db, options) {
+    for (const name of [options.from, options.to])
+        if (!options.disks.includes(name))
+            throw new Error(`Unknown disk: ${name}`);
+    if (options.from === options.to)
+        throw new Error('Source and target disks must differ');
+    const rows = await db('attachments')
+        .where('disk', options.from)
+        .whereNull('deleted_at')
+        .orderBy('id')
+        .select('id', 'path', 'size');
+    const result = {
+        from: options.from,
+        to: options.to,
+        dryRun: Boolean(options.dryRun),
+        total: rows.length,
+        copied: 0,
+        skipped: 0,
+        failed: [],
+        remaining: rows.length,
+    };
+    const report = options.report ?? (() => { });
+    if (options.dryRun) {
+        for (const row of rows)
+            report(`would copy #${row.id} ${row.path} (${row.size} bytes)`);
+        return result;
+    }
+    const source = options.use(options.from);
+    const target = options.use(options.to);
+    for (const row of rows) {
+        const size = Number(row.size);
+        try {
+            let present = false;
+            if (await target.exists(row.path)) {
+                const existing = await target.getMetaData(row.path);
+                present = existing.contentLength === size;
+            }
+            if (!present) {
+                await target.putStream(row.path, await source.getStream(row.path));
+                const written = await target.getMetaData(row.path);
+                if (written.contentLength !== size)
+                    throw new Error(`size mismatch after copy: expected ${size}, found ${written.contentLength}`);
+            }
+            await db.transaction((trx) => trx('attachments').where({ id: row.id, disk: options.from }).update({ disk: options.to }));
+            if (present)
+                result.skipped++;
+            else
+                result.copied++;
+            result.remaining--;
+            report(`${present ? 'verified' : 'copied'} #${row.id} ${row.path}`);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            result.failed.push({ id: Number(row.id), path: row.path, reason });
+            report(`failed #${row.id} ${row.path}: ${reason}`);
+        }
+    }
+    return result;
+}

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

@@ -0,0 +1,22 @@
+import { Ability } from '@casl/ability';
+import type { Conditions } from './conditions.js';
+import type { RecordData, Resource } from '../resource/types.js';
+export type Rule = {
+    subject: string;
+    action: string | string[];
+    conditions?: Conditions;
+    fields?: string[];
+    inverted?: boolean;
+};
+export type Actor = {
+    id: number;
+    orgPaths: string[];
+    permissionLevel: number;
+    rules: Rule[];
+};
+export type KitAbility = Ability<[string, any], Conditions>;
+export declare const abilitySchemas: WeakMap<KitAbility, readonly Pick<Resource, "fields" | "name">[]>;
+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;
+export declare function conditionFields(ability: KitAbility, resource: Resource): string[];

package/build/src/auth/ability.js

@@ -0,0 +1,31 @@
+import { Ability, subject, fieldPatternMatcher } from '@casl/ability';
+import { conditionsMatcher, predicates } from './conditions.js';
+export const abilitySchemas = new WeakMap();
+export function buildAbility(rules, schemas = []) {
+    for (const rule of rules) {
+        predicates(rule.conditions);
+        if (rule.fields?.length === 0)
+            throw new Error('An empty fields rule is invalid');
+    }
+    const ability = new Ability([...rules.filter((r) => !r.inverted), ...rules.filter((r) => r.inverted)], {
+        conditionsMatcher: (conditions) => conditionsMatcher(conditions, schemas),
+        fieldMatcher: fieldPatternMatcher,
+    });
+    abilitySchemas.set(ability, schemas);
+    return ability;
+}
+export function inOrgScope(path, paths) {
+    return (typeof path === 'string' &&
+        paths.some((parent) => path === parent || path.startsWith(`${parent}.`)));
+}
+export function canRecord(ability, actor, resource, action, record, field) {
+    return ((!resource.scoped || inOrgScope(record.orgPath, actor.orgPaths)) &&
+        ability.can(action, subject(resource.name, record), field));
+}
+export function conditionFields(ability, resource) {
+    return [
+        ...new Set(ability.rules
+            .filter((r) => r.subject === resource.name || r.subject === 'all')
+            .flatMap((r) => Object.keys(r.conditions ?? {}))),
+    ];
+}

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

@@ -0,0 +1,14 @@
+import type { Knex } from 'knex';
+import type { Actor } from './ability.js';
+import type { ResourceRegistry } from '../resource/registry.js';
+export interface ActorCache {
+    get(key: string): Promise<Actor | undefined>;
+    set(key: string, value: Actor): Promise<void>;
+}
+export declare class ActorStore {
+    private db;
+    private registry;
+    private cache?;
+    constructor(db: Knex, registry: ResourceRegistry, cache?: ActorCache | undefined);
+    load(id: number): Promise<Actor>;
+}

package/build/src/auth/actor_store.js

@@ -0,0 +1,65 @@
+export class ActorStore {
+    db;
+    registry;
+    cache;
+    constructor(db, registry, cache) {
+        this.db = db;
+        this.registry = registry;
+        this.cache = cache;
+    }
+    async load(id) {
+        // Revision is read on every request; DB triggers invalidate across workers and tree moves.
+        const { version } = await this.db('authorization_revision').where({ id: 1 }).first('version');
+        const key = `ability:${id}:${version}`;
+        const cached = await this.cache?.get(key);
+        if (cached)
+            return cached;
+        const memberships = await this.db('user_org_units as u')
+            .join('org_units as o', 'o.id', 'u.org_unit_id')
+            .where('u.user_id', id)
+            .select('o.path');
+        const assignments = await this.db('user_roles as ur')
+            .join('roles as r', 'r.id', 'ur.role_id')
+            .leftJoin('org_units as o', 'o.id', 'ur.org_unit_id')
+            .join('role_rules as rr', 'rr.role_id', 'r.id')
+            .where('ur.user_id', id)
+            .select('rr.*', 'r.permission_level', 'o.path as role_path');
+        const rules = [];
+        let permissionLevel = 0;
+        for (const row of assignments) {
+            // Privileged field access only comes from deployment-wide roles.
+            if (!row.role_path)
+                permissionLevel = Math.max(permissionLevel, row.permission_level);
+            const rule = {
+                subject: row.subject,
+                action: row.action,
+                conditions: row.conditions ?? undefined,
+                fields: row.fields ?? undefined,
+                inverted: row.inverted,
+            };
+            if (!row.role_path) {
+                rules.push(rule);
+                continue;
+            }
+            for (const resource of this.registry
+                .all()
+                .filter((r) => r.scoped && (rule.subject === 'all' || rule.subject === r.name))) {
+                if (rule.conditions?.orgPath)
+                    throw new Error('orgPath is reserved for role scope');
+                rules.push({
+                    ...rule,
+                    subject: resource.name,
+                    conditions: { ...rule.conditions, orgPath: row.role_path },
+                });
+                rules.push({
+                    ...rule,
+                    subject: resource.name,
+                    conditions: { ...rule.conditions, orgPath: { $like: `${row.role_path}.%` } },
+                });
+            }
+        }
+        const actor = { id, orgPaths: memberships.map((r) => r.path), permissionLevel, rules };
+        await this.cache?.set(key, actor);
+        return actor;
+    }
+}

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

@@ -0,0 +1,11 @@
+import type { Scalar, RecordData, Resource } from '../resource/types.js';
+export type Operator = '$eq' | '$ne' | '$in' | '$lt' | '$gt' | '$like';
+export type Conditions = Record<string, Scalar | Partial<Record<Operator, Scalar | Scalar[]>>>;
+export type Predicate = {
+    field: string;
+    operator: Operator;
+    value: Scalar | Scalar[];
+};
+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

@@ -0,0 +1,81 @@
+import { columnName } from '../resource/define_resource.js';
+const operators = new Set(['$eq', '$ne', '$in', '$lt', '$gt', '$like']);
+const scalar = (v) => v === null ||
+    ['string', 'boolean'].includes(typeof v) ||
+    (typeof v === 'number' && Number.isFinite(v));
+export function predicates(conditions = {}, fields) {
+    if (!conditions || Array.isArray(conditions) || typeof conditions !== 'object')
+        throw new Error('Conditions must be an object');
+    return Object.entries(conditions).flatMap(([field, condition]) => {
+        columnName(field);
+        if (fields && !fields.has(field))
+            throw new Error(`Unknown condition field: ${field}`);
+        const ops = scalar(condition) ? { $eq: condition } : condition;
+        if (!ops || Array.isArray(ops) || typeof ops !== 'object' || !Object.keys(ops).length)
+            throw new Error(`Invalid condition: ${field}`);
+        return Object.entries(ops).map(([operator, value]) => {
+            if (!operators.has(operator))
+                throw new Error(`Unsupported condition operator: ${operator}`);
+            if (operator === '$in' ? !Array.isArray(value) || !value.every(scalar) : !scalar(value))
+                throw new Error(`Invalid operand: ${operator}`);
+            if (operator === '$like' && typeof value !== 'string')
+                throw new Error('$like requires a string');
+            if (['$lt', '$gt'].includes(operator) && !['string', 'number'].includes(typeof value))
+                throw new Error(`${operator} requires a number or string`);
+            return { field, operator: operator, value: value };
+        });
+    });
+}
+// SQL LIKE semantics: % and _ are wildcards, backslash is a literal character.
+export function likePattern(value) {
+    return new RegExp(`^${[...value].map((c) => (c === '%' ? '[\\s\\S]*' : c === '_' ? '[\\s\\S]' : c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))).join('')}$`, 'u');
+}
+// This matcher is used exclusively by CASL. SQL compilation shares the validated AST.
+export function conditionsMatcher(conditions, schemas = []) {
+    const parts = predicates(conditions);
+    return (record) => parts.every(({ field, operator, value }) => {
+        const actual = record[field] ?? null;
+        const type = schemas.find((schema) => schema.name === record.__caslSubjectType__)?.fields[field]?.type;
+        const compare = () => {
+            if (type === 'money') {
+                if (typeof actual !== 'string' ||
+                    typeof value !== 'string' ||
+                    !/^(0|-?[1-9]\d*)$/.test(actual) ||
+                    !/^(0|-?[1-9]\d*)$/.test(value))
+                    return undefined;
+                const left = BigInt(actual);
+                const right = BigInt(value);
+                return left < right ? -1 : left > right ? 1 : 0;
+            }
+            if (typeof actual !== typeof value || actual === null)
+                return undefined;
+            if (typeof actual === 'string' && typeof value === 'string') {
+                const left = [...actual].map((point) => point.codePointAt(0));
+                const right = [...value].map((point) => point.codePointAt(0));
+                for (let index = 0; index < Math.min(left.length, right.length); index++)
+                    if (left[index] !== right[index])
+                        return left[index] < right[index] ? -1 : 1;
+                return Math.sign(left.length - right.length);
+            }
+            return actual < value
+                ? -1
+                : actual > value
+                    ? 1
+                    : 0;
+        };
+        switch (operator) {
+            case '$eq':
+                return actual === value;
+            case '$ne':
+                return actual !== value;
+            case '$in':
+                return value.includes(actual);
+            case '$lt':
+                return compare() === -1;
+            case '$gt':
+                return compare() === 1;
+            case '$like':
+                return typeof actual === 'string' && likePattern(value).test(actual);
+        }
+    });
+}

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

@@ -0,0 +1,4 @@
+import { type Actor } from './ability.js';
+import type { Resource } from '../resource/types.js';
+/** UI hints only. Organizational scope and every mutation are enforced on the server. */
+export declare function packedResourceRules(resource: Resource, actor: Actor): import("@casl/ability/extra").PackRule<import("@casl/ability").SubjectRawRule<string, any, import("./conditions.ts").Conditions>>[];

package/build/src/auth/packed_rules.js

@@ -0,0 +1,13 @@
+import { packRules } from '@casl/ability/extra';
+import { buildAbility } from './ability.js';
+/** UI hints only. Organizational scope and every mutation are enforced on the server. */
+export function packedResourceRules(resource, actor) {
+    const rules = actor.rules
+        .filter((rule) => rule.subject === resource.name || rule.subject === 'all')
+        .map((rule) => ({ ...rule, subject: resource.name }));
+    const forbidden = Object.keys(resource.fields).filter((key) => actor.permissionLevel <
+        Math.max(resource.fields[key].permissionLevel ?? 0, resource.hidden?.includes(key) ? 1 : 0));
+    if (forbidden.length)
+        rules.push({ subject: resource.name, action: 'manage', fields: forbidden, inverted: true });
+    return packRules(buildAbility(rules).rules);
+}

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

@@ -0,0 +1,11 @@
+import type { Knex } from 'knex';
+import type { KitAbility, Actor } from './ability.js';
+import { type Conditions } from './conditions.js';
+import type { Resource } from '../resource/types.js';
+export type Sql = {
+    text: string;
+    bindings: Knex.RawBinding[];
+};
+export declare function conditionSql(conditions: Conditions | undefined, resource: Resource): Sql;
+export declare function authorizationSql(ability: KitAbility, action: string, resource: Resource, field?: string): Sql;
+export declare function accessibleBy(query: Knex.QueryBuilder, ability: KitAbility, actor: Actor, action: string, resource: Resource): Knex.QueryBuilder<any, any>;