@appxdigital/appx-core 0.1.128 → 0.1.130

package/dist/prisma/prisma.service.d.ts

@@ -111,6 +111,48 @@ export declare class PrismaService {
      * conditions are injected, so it never blocks the framework's own conditions.
      */
     private assertFilterFieldsReadable;
+    /**
+     * The read args nested in a selection — each selected relation's args and
+     * each `_count` entry — paired with the model they read, so client
+     * filters are checked/scoped at every level.
+     */
+    private nestedReadArgs;
+    /**
+     * Rewrite every relation filter in the CLIENT's `where` (top level and in
+     * nested relation selections) so it only takes into account related rows
+     * this role can read. Runs on the client input, before the trusted ABAC
+     * conditions are injected, so those are never rewritten.
+     */
+    private scopeClientFilters;
+    /**
+     * Rewrite one client `where` clause: each relation filter is narrowed to the
+     * related rows the role can read (`some`/`none`/`is`/`isNot` AND the target's
+     * read conditions; `every` holds over the readable rows only). A relation
+     * into a model with no read rule for the role is rejected.
+     */
+    private scopeRelationFilters;
+    /**
+     * Applies `fn` to the filter inside each operator of a relation filter
+     * (`some`/`every`/`none`, `is`/`isNot`), or to the to-one shorthand
+     * (`rel: { ... }` ≡ `rel: { is: { ... } }`) as a whole, with no operator.
+     */
+    private static mapRelationFilter;
+    /**
+     * The resolved read conditions a relation's target imposes on this role, or
+     * `undefined` when it imposes none (exposed model or 'ALL'). A target with no
+     * read rule is rejected, naming the relation as the field being filtered or
+     * ordered by.
+     */
+    private relationReadConditions;
+    /**
+     * Makes a condition strictly true/false in SQL. A comparison on a nullable
+     * column is NULL (not false) when the column is NULL, and under a negation
+     * (`isNot`, `NOT`, which Prisma inlines for to-one relations) NULL stays NULL
+     * — so the outcome would depend on the rest of the filter. Guarding each
+     * such comparison with `IS NOT NULL` turns NULL into false; where the
+     * condition is used positively the result is unchanged.
+     */
+    private nullSafeConditions;
     /** Recursively assert no omitted field is referenced in a where/orderBy clause. */
     private assertClauseFieldsReadable;
     /**
@@ -123,6 +165,33 @@ export declare class PrismaService {
     private isPresenceOnlyPredicate;
     private throwUnreadableFilterField;
     private applyWhereConditions;
+    /**
+     * Merges a to-one relation's read conditions into a `where`. If the relation
+     * is optional, rows where it is null are kept.
+     */
+    private static mergeToOneConditions;
+    /**
+     * The to-one read conditions an `orderBy` brings in: ordering by a related
+     * field (at any depth) requires that related record to be readable, like
+     * selecting it. Ordering by a to-many relation's count is only allowed when
+     * the related model is fully readable (a count can't be scoped).
+     */
+    private orderByRelationConditions;
+    /**
+     * Scopes a `_count` selection: each counted to-many relation only counts the
+     * related rows the role can read. A relation into a model with no read rule
+     * is rejected, as selecting it would be. Left untouched when nothing needs
+     * scoping.
+     */
+    private applyCountConditions;
+    /**
+     * Writes the rule's `set` values into every row of a write's `data`,
+     * overriding what the client sent (placeholders such as `$USER_ID` are
+     * resolved). Runs before the write is authorized, so the set values are
+     * checked like any other: against the create `conditions`, and a set
+     * foreign key against its `connect` rule.
+     */
+    private applySetValues;
     /**
      * Enforces permission `conditions` on `create` / `createMany`.
      *

package/dist/prisma/prisma.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prisma.service.d.ts","sourceRoot":"","sources":["../../src/prisma/prisma.service.ts"],"names":[],"mappings":";AACA,OAAO,EAAC,MAAM,EAAE,YAAY,EAAC,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAC,qBAAqB,EAAkB,MAAM,yCAAyC,CAAC;AAG/F,OAAO,KAAK,EAAC,YAAY,IAAI,aAAa,EAAC,MAAM,gBAAgB,CAAC;AAGlE,OAAO,EAAC,iBAAiB,EAAC,MAAM,kBAAkB,CAAC;AAEnD,eAAO,MAAM,iBAAiB;mBACX,MAAM,EAAE;EACvB,CAAC;AAEL,KAAK,QAAQ,GAAG,MAAM,aAAa,CAAC;AAEpC,oDAAoD;AACpD,MAAM,MAAM,iBAAiB,GAAG;IAC5B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,4EAA4E;AAC5E,KAAK,QAAQ,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;AAEtE;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,YAAY,GAAG,mBAAmB,GAAG,QAAQ,GAAG,QAAQ,CAAC,GAAG;IACjG,UAAU,EAAE,QAAQ,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IACrC,iBAAiB,EAAE,QAAQ,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC;IACnD,MAAM,EAAE,QAAQ,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;IAClC,MAAM,EAAE,QAAQ,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;CACrC,CAAC;AAGF,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,QAAQ,IAAI,eAAe,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;AAEpF;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;KAC7B,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;QAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAA;KAAE,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACpG,CAAC;AAEF,qBACa,aAAa;IAaY,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAZpE,OAAO,CAAC,YAAY,CAA2B;IAC/C,YAAY,EAAE,YAAY,CAAC;IAC3B;;;;;OAKG;IACH,OAAO,CAAC,SAAS,CAAgB;gBAG7B,YAAY,EAAE,YAAY,EACqB,iBAAiB,EAAE,qBAAqB;IAQ3F;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IA6B3B,YAAY,CAAC,MAAM,EAAE,OAAO;IAO5B,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAWjE,OAAO,CAAC,KAAK;IAQb,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC;IAIpE,WAAW;IAuFX;;;;OAIG;IACH,gBAAgB,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;IAoBlE,IAAI,KAAK,IAAI,gBAAgB,CAAC,aAAa,CAAC,CAU3C;IAED,IAAI,IAAI,IAAI,eAAe,CAAC,MAAM,CAAC,CAElC;IAED,IAAI,OAAO,IAAI,eAAe,CAAC,SAAS,CAAC,CAExC;IAED,IAAI,gBAAgB,QAEnB;IAED;;;OAGG;IACH,WAAW;IA+DX;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAkE1B,IAAI,2BAA2B,QAM9B;IAED;;;;;;;;;;;OAWG;IACH;;;;;;;OAOG;IACH,OAAO,CAAC,0BAA0B;IAYlC,mFAAmF;IACnF,OAAO,CAAC,0BAA0B;IAgDlC;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;IAQ/B,OAAO,CAAC,0BAA0B;IAOlC,OAAO,CAAC,oBAAoB;IA8K5B;;;;;;;;;;;;;;;;OAgBG;YACW,uBAAuB;IAkDrC;;;;;;;;;;;;;;;;;;;OAmBG;YACW,mBAAmB;IA2BjC,0EAA0E;YAC5D,wBAAwB;IAmCtC,yGAAyG;IACzG,OAAO,CAAC,gBAAgB;IAWxB,4FAA4F;IAC5F,OAAO,CAAC,eAAe;IAcvB;;;;;;;;OAQG;YACW,oBAAoB;IA6ClC;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAKjB;;;;;;OAMG;YACW,2BAA2B;IAqBzC;;;;;;OAMG;IACH,OAAO,CAAC,yBAAyB;IAmBjC;;;;;;;OAOG;YACW,uBAAuB;IA8BrC,oGAAoG;IACpG,OAAO,CAAC,mBAAmB;IAwB3B;;;;;;;OAOG;WACW,gBAAgB,CAAC,UAAU,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,GAAG,GAAG,GAAG;IAgBjE;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IA2BlC;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE;IAI5C;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAUvB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,iBAAiB;IA8EzB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,IAAI,GAAG;QAC5E,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,OAAO,CAAA;KACtB;IAoBD,gBAAgB,CAAC,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAyBzF"}
+{"version":3,"file":"prisma.service.d.ts","sourceRoot":"","sources":["../../src/prisma/prisma.service.ts"],"names":[],"mappings":"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"}

package/dist/prisma/prisma.service.js

@@ -20,6 +20,7 @@ const permissionsConfigTypes_1 = require("../common/config/permissionsConfigType
 const permissions_validator_1 = require("./permissions-validator");
 const nestjs_request_context_1 = require("nestjs-request-context");
 const node_async_hooks_1 = require("node:async_hooks");
+const schema_annotations_util_1 = require("../common/utils/schema-annotations.util");
 exports.CorePrismaContext = new node_async_hooks_1.AsyncLocalStorage();
 let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaService {
     constructor(prismaClient, permissionsConfig) {
@@ -128,6 +129,7 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                                     }
                                     if (!options?.BYPASS_FILTERING) {
                                         if (['create', 'createMany'].includes(methodKey.toString())) {
+                                            this.applySetValues(String(propKey), userRole, params.data, user, methodKey.toString());
                                             // Conditions can't be pushed into a WHERE on insert, so
                                             // validate the incoming data satisfies them before insert.
                                             await this.enforceCreateConditions(String(propKey), userRole, params, user, methodKey.toString());
@@ -141,10 +143,14 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                                             // field omission). Runs on the client input, BEFORE the
                                             // trusted ABAC conditions are injected below.
                                             this.assertFilterFieldsReadable(String(propKey), userRole, params);
+                                            // Scope the client's relation filters to related rows this
+                                            // role can read — also on the client input, before injection.
+                                            params = this.scopeClientFilters(String(propKey), userRole, params, user);
                                             params = this.applyWhereConditions(String(propKey), userRole, params, user, methodKey);
                                             // An update can re-point a foreign key (scalar column);
                                             // authorize those changes with the same connect rules as create.
                                             if (['update', 'updateMany'].includes(methodKey.toString())) {
+                                                this.applySetValues(String(propKey), userRole, params.data, user, methodKey.toString());
                                                 await this.enforceNestedWrites(String(propKey), params.data, user, userRole);
                                             }
                                         }
@@ -230,10 +236,11 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
             const scalarFields = [];
             const relationFields = {};
             const noWriteFields = [];
+            const nullableFields = [];
             for (const field of fields) {
                 let field_name = field.name;
                 const fieldType = field.type;
-                const commentPart = field.documentation || '';
+                const commentPart = (0, schema_annotations_util_1.annotationText)(field.documentation);
                 if (commentPart) {
                     const roleMatch = commentPart.match(/@Role\((.*?)\)/);
                     if (roleMatch) {
@@ -248,6 +255,9 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                 fieldTypes[field_name] = fieldType;
                 if (field.kind === 'scalar' || field.kind === 'enum') {
                     scalarFields.push(field_name);
+                    if (!field.isRequired && !field.isList && fieldType !== 'Json') {
+                        nullableFields.push(field_name);
+                    }
                 }
                 else {
                     relationFields[field_name] = {
@@ -272,6 +282,7 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                 scalarFields,
                 relationFields,
                 noWriteFields,
+                nullableFields,
             };
         }
     }
@@ -377,6 +388,152 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                     this.throwUnreadableFilterField(modelName, field, userRole, 'distinct');
             }
         }
+        for (const [relatedModel, nested] of this.nestedReadArgs(modelName, args)) {
+            this.assertFilterFieldsReadable(relatedModel, userRole, nested);
+        }
+    }
+    /**
+     * The read args nested in a selection — each selected relation's args and
+     * each `_count` entry — paired with the model they read, so client
+     * filters are checked/scoped at every level.
+     */
+    nestedReadArgs(modelName, args) {
+        const projection = args.select ?? args.include;
+        if (!projection || typeof projection !== 'object')
+            return [];
+        const nested = [];
+        for (const key of Object.keys(projection)) {
+            const isCount = key === '_count';
+            const entries = isCount ? projection[key]?.select : { [key]: projection[key] };
+            if (!entries || typeof entries !== 'object')
+                continue;
+            for (const field of Object.keys(entries)) {
+                const relation = this.getRelation(modelName, field);
+                if (relation && entries[field] && typeof entries[field] === 'object')
+                    nested.push([relation.model, entries[field]]);
+            }
+        }
+        return nested;
+    }
+    /**
+     * Rewrite every relation filter in the CLIENT's `where` (top level and in
+     * nested relation selections) so it only takes into account related rows
+     * this role can read. Runs on the client input, before the trusted ABAC
+     * conditions are injected, so those are never rewritten.
+     */
+    scopeClientFilters(modelName, userRole, args, user) {
+        if (!args || typeof args !== 'object')
+            return args;
+        if (args.where)
+            args.where = this.scopeRelationFilters(modelName, userRole, args.where, user);
+        for (const [relatedModel, nested] of this.nestedReadArgs(modelName, args)) {
+            this.scopeClientFilters(relatedModel, userRole, nested, user);
+        }
+        return args;
+    }
+    /**
+     * Rewrite one client `where` clause: each relation filter is narrowed to the
+     * related rows the role can read (`some`/`none`/`is`/`isNot` AND the target's
+     * read conditions; `every` holds over the readable rows only). A relation
+     * into a model with no read rule for the role is rejected.
+     */
+    scopeRelationFilters(modelName, userRole, clause, user) {
+        if (Array.isArray(clause))
+            return clause.map((c) => this.scopeRelationFilters(modelName, userRole, c, user));
+        if (!clause || typeof clause !== 'object')
+            return clause;
+        const scoped = {};
+        for (const key of Object.keys(clause)) {
+            const value = clause[key];
+            if (key === 'AND' || key === 'OR' || key === 'NOT') {
+                scoped[key] = this.scopeRelationFilters(modelName, userRole, value, user);
+                continue;
+            }
+            const relation = this.getRelation(modelName, key);
+            if (!relation || !value || typeof value !== 'object') {
+                scoped[key] = value; // scalar filter, or a to-one presence check (`rel: null`)
+                continue;
+            }
+            const conditions = this.relationReadConditions(modelName, key, relation, userRole, user, 'where');
+            scoped[key] = PrismaService_1.mapRelationFilter(relation, value, (op, filter) => {
+                if (filter === null)
+                    return null; // `is: null` / `isNot: null`
+                const inner = this.scopeRelationFilters(relation.model, userRole, filter, user);
+                if (!conditions)
+                    return inner;
+                return op === 'every' ? { OR: [inner, { NOT: conditions }] } : { AND: [inner, conditions] };
+            });
+        }
+        return scoped;
+    }
+    /**
+     * Applies `fn` to the filter inside each operator of a relation filter
+     * (`some`/`every`/`none`, `is`/`isNot`), or to the to-one shorthand
+     * (`rel: { ... }` ≡ `rel: { is: { ... } }`) as a whole, with no operator.
+     */
+    static mapRelationFilter(relation, value, fn) {
+        const hasOperators = value && typeof value === 'object'
+            && (relation.relation === 'hasMany' || 'is' in value || 'isNot' in value);
+        if (!hasOperators)
+            return fn(null, value);
+        return Object.fromEntries(Object.keys(value).map((op) => [op, fn(op, value[op])]));
+    }
+    /**
+     * The resolved read conditions a relation's target imposes on this role, or
+     * `undefined` when it imposes none (exposed model or 'ALL'). A target with no
+     * read rule is rejected, naming the relation as the field being filtered or
+     * ordered by.
+     */
+    relationReadConditions(modelName, field, relation, userRole, user, kind) {
+        const exposedModels = (exports.CorePrismaContext.getStore()?.exposedModels || []).map((m) => m.toLowerCase());
+        if (exposedModels.includes(relation.model.toLowerCase()))
+            return undefined;
+        const permissions = this.normalizedPermissionsConfig[relation.model.toLowerCase()]?.[userRole] || {};
+        const action = relation.relation === 'belongsTo' ? 'findFirst' : 'findMany';
+        const relatedPermissions = this.selectPermission(permissions, action, relation.model, userRole);
+        if (!relatedPermissions) {
+            if (kind !== 'select')
+                this.throwUnreadableFilterField(modelName, field, userRole, kind);
+            console.debug(`No permissions found for action '${relation.model}.${action}()' on role ${userRole}`);
+            throw new common_1.HttpException('Missing permissions on model ' + relation.model, common_1.HttpStatus.FORBIDDEN);
+        }
+        if (relatedPermissions === 'ALL')
+            return undefined;
+        return this.nullSafeConditions(relation.model, PrismaService_1._buildConditions(relatedPermissions.conditions, user));
+    }
+    /**
+     * Makes a condition strictly true/false in SQL. A comparison on a nullable
+     * column is NULL (not false) when the column is NULL, and under a negation
+     * (`isNot`, `NOT`, which Prisma inlines for to-one relations) NULL stays NULL
+     * — so the outcome would depend on the rest of the filter. Guarding each
+     * such comparison with `IS NOT NULL` turns NULL into false; where the
+     * condition is used positively the result is unchanged.
+     */
+    nullSafeConditions(modelName, clause) {
+        if (Array.isArray(clause))
+            return clause.map((c) => this.nullSafeConditions(modelName, c));
+        if (!clause || typeof clause !== 'object')
+            return clause;
+        const nullableFields = this.fieldConfigs[modelName.toLowerCase()].nullableFields;
+        const guards = [];
+        const safe = {};
+        for (const key of Object.keys(clause)) {
+            const value = clause[key];
+            if (key === 'AND' || key === 'OR' || key === 'NOT') {
+                safe[key] = this.nullSafeConditions(modelName, value);
+                continue;
+            }
+            const relation = this.getRelation(modelName, key);
+            if (relation) {
+                safe[key] = PrismaService_1.mapRelationFilter(relation, value, (_op, filter) => this.nullSafeConditions(relation.model, filter));
+                continue;
+            }
+            if (nullableFields.includes(key) && value !== undefined && !this.isPresenceOnlyPredicate(value)) {
+                guards.push({ [key]: { not: null } });
+            }
+            safe[key] = value;
+        }
+        return guards.length ? { AND: [...guards, safe] } : safe;
     }
     /** Recursively assert no omitted field is referenced in a where/orderBy clause. */
     assertClauseFieldsReadable(modelName, userRole, clause, kind) {
@@ -467,14 +624,16 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                 throw new common_1.HttpException('Missing permissions on model ' + modelName, common_1.HttpStatus.FORBIDDEN);
             }
         }
-        if (args.select) {
-            for (const field of Object.keys(args.select)) {
+        // `include` reaches here only when field omission was bypassed (omission
+        // rewrites it to `select`); relations are filtered the same either way.
+        const projection = args.select ?? args.include;
+        if (projection) {
+            for (const field of Object.keys(projection)) {
                 // If field is relation
                 let relation = this.getRelation(modelName, field);
                 if (!relation) {
                     if (field === '_count') {
-                        // TODO implement filtering on _count
-                        // args.select[field] = this.applyWhereConditions(modelName, userRole, args.select[field], user, action);
+                        projection[field] = this.applyCountConditions(modelName, userRole, projection[field], user);
                     }
                     continue;
                 }
@@ -482,24 +641,38 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                     this.debug(`Found 1:1 / *:1 (belongsTo) relation to model '${relation.model}' from model '${modelName}' via field '${field}'. Filter will be applied to main conditions...`);
                     // findFirst permissions for related model
                     const relatedPermissions = this.selectPermission(permissionsConfig[relation.model.toLowerCase()]?.[userRole] || {}, 'findFirst', relation.model, userRole);
+                    let conditions;
                     // If model is exposed, do not apply conditions
                     if (exposedModels.includes(relation.model.toLowerCase())) {
                         this.debug(`Related model '${relation.model}' is exposed via @Permission() decorator. Skipping conditions for action '${String(action)}' on role ${userRole}.`);
-                        continue;
                     }
-                    if (!relatedPermissions) {
-                        console.debug(`No permissions found for action '${relation.model}.${String(action)}()' on role ${userRole}`);
-                        throw new common_1.HttpException('Missing permissions on model ' + relation.model, common_1.HttpStatus.FORBIDDEN);
+                    else {
+                        if (!relatedPermissions) {
+                            console.debug(`No permissions found for action '${relation.model}.${String(action)}()' on role ${userRole}`);
+                            throw new common_1.HttpException('Missing permissions on model ' + relation.model, common_1.HttpStatus.FORBIDDEN);
+                        }
+                        if (relatedPermissions === 'ALL') {
+                            this.debug(`Related model '${relation.model}' has 'ALL' permissions for action '${String(action)}' on role ${userRole}. No conditions to apply.`);
+                        }
+                        else {
+                            conditions = PrismaService_1._buildConditions(relatedPermissions?.conditions, user);
+                        }
                     }
-                    if (relatedPermissions === 'ALL') {
-                        this.debug(`Related model '${relation.model}' has 'ALL' permissions for action '${String(action)}' on role ${userRole}. No conditions to apply.`);
-                        continue;
+                    // Relations selected below this one are filtered too: the related
+                    // model's own to-one conditions merge into `conditions` (Prisma
+                    // can't take a `where` on a to-one selection), and its to-many
+                    // relations are filtered in place.
+                    const nested = projection[field];
+                    if (nested && typeof nested === 'object' && (nested.select || nested.include)) {
+                        conditions = this.applyWhereConditions(relation.model, userRole, { select: nested.select, include: nested.include }, user, 'findFirst').where;
+                    }
+                    if (conditions) {
+                        belongsToQueue.push({
+                            field,
+                            relation,
+                            conditions,
+                        });
                     }
-                    belongsToQueue.push({
-                        field,
-                        relation,
-                        relatedPermissions,
-                    });
                     continue;
                 }
                 this.debug(`Found 1:N / N:N (hasMany) relation to model '${relation.model}' from model '${modelName}' via field '${field}'. Applying filter to the relation...`);
@@ -517,54 +690,29 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                   },
                 })
                  */
-                if (args.select[field] === true) {
-                    args.select[field] = {};
+                if (projection[field] === true) {
+                    projection[field] = {};
                 }
                 // findMany permissions for related model
-                args.select[field].where = this.applyWhereConditions(relation.model, userRole, args.select[field], user, 'findMany').where;
-                delete args.select[field].select.where;
+                projection[field].where = this.applyWhereConditions(relation.model, userRole, projection[field], user, 'findMany').where;
+                if (projection[field].select) {
+                    delete projection[field].select.where;
+                }
             }
         }
+        // Ordering by a related to-one field applies that model's read rules the
+        // same way selecting it does: rows whose related record isn't readable
+        // don't take part in the ordering.
+        belongsToQueue.push(...this.orderByRelationConditions(modelName, userRole, args.orderBy, user));
         if (belongsToQueue?.length > 0) {
             this.debug(`Merging belongsTo relation conditions into main ${modelName}.`, 'warn');
         }
         for (const entry of belongsToQueue) {
-            const { relatedPermissions, field, relation } = entry;
-            this.debug(`Merging conditions for belongsTo relation field '${field}': ${JSON.stringify(relatedPermissions?.conditions)}`, 'info');
-            let belongsToConditions = PrismaService_1._buildConditions(relatedPermissions?.conditions, user);
+            const { conditions, field, relation } = entry;
+            this.debug(`Merging conditions for belongsTo relation field '${field}': ${JSON.stringify(conditions)}`, 'info');
             if (!args.where)
                 args.where = {};
-            // If relation is optional allow for non-matching records
-            if (relation.isRequired === false) {
-                args.where = {
-                    OR: [
-                        {
-                            ...args.where,
-                            [field]: {
-                                AND: [
-                                    args?.where?.[field] ?? {},
-                                    belongsToConditions
-                                ]
-                            }
-                        },
-                        {
-                            ...args.where,
-                            [field]: { is: null }
-                        }
-                    ]
-                };
-            }
-            else {
-                args.where = {
-                    ...(args.where || {}),
-                    [field]: {
-                        AND: [
-                            args?.where?.[field] ?? {},
-                            belongsToConditions
-                        ]
-                    }
-                };
-            }
+            args.where = PrismaService_1.mergeToOneConditions(args.where, field, relation, conditions);
         }
         // If model is exposed, do not apply conditions
         if (exposedModels.includes(modelName.toLowerCase())) {
@@ -585,6 +733,122 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
         }
         return args;
     }
+    /**
+     * Merges a to-one relation's read conditions into a `where`. If the relation
+     * is optional, rows where it is null are kept.
+     */
+    static mergeToOneConditions(where, field, relation, conditions) {
+        if (relation.isRequired === false) {
+            return {
+                OR: [
+                    {
+                        ...where,
+                        [field]: {
+                            AND: [
+                                where[field] ?? {},
+                                conditions
+                            ]
+                        }
+                    },
+                    {
+                        ...where,
+                        [field]: { is: null }
+                    }
+                ]
+            };
+        }
+        return {
+            ...where,
+            [field]: {
+                AND: [
+                    where[field] ?? {},
+                    conditions
+                ]
+            }
+        };
+    }
+    /**
+     * The to-one read conditions an `orderBy` brings in: ordering by a related
+     * field (at any depth) requires that related record to be readable, like
+     * selecting it. Ordering by a to-many relation's count is only allowed when
+     * the related model is fully readable (a count can't be scoped).
+     */
+    orderByRelationConditions(modelName, userRole, orderBy, user) {
+        const entries = [];
+        for (const clause of [].concat(orderBy ?? [])) {
+            if (!clause || typeof clause !== 'object')
+                continue;
+            for (const field of Object.keys(clause)) {
+                const relation = this.getRelation(modelName, field);
+                if (!relation)
+                    continue;
+                let conditions = this.relationReadConditions(modelName, field, relation, userRole, user, 'orderBy');
+                if (relation.relation !== 'belongsTo') {
+                    if (conditions)
+                        this.throwUnreadableFilterField(modelName, field, userRole, 'orderBy');
+                    continue;
+                }
+                const deeper = this.orderByRelationConditions(relation.model, userRole, clause[field], user)
+                    .reduce((where, e) => PrismaService_1.mergeToOneConditions(where, e.field, e.relation, e.conditions), {});
+                if (Object.keys(deeper).length)
+                    conditions = conditions ? { AND: [conditions, deeper] } : deeper;
+                if (conditions)
+                    entries.push({ field, relation, conditions });
+            }
+        }
+        return entries;
+    }
+    /**
+     * Scopes a `_count` selection: each counted to-many relation only counts the
+     * related rows the role can read. A relation into a model with no read rule
+     * is rejected, as selecting it would be. Left untouched when nothing needs
+     * scoping.
+     */
+    applyCountConditions(modelName, userRole, value, user) {
+        const relationFields = this.fieldConfigs[modelName.toLowerCase()].relationFields;
+        // `_count: true` counts every to-many relation.
+        const counted = value === true
+            ? Object.fromEntries(Object.keys(relationFields).filter((f) => relationFields[f].relation === 'hasMany').map((f) => [f, true]))
+            : value?.select;
+        if (!counted || typeof counted !== 'object')
+            return value;
+        let scoped;
+        for (const field of Object.keys(counted)) {
+            const relation = this.getRelation(modelName, field);
+            if (!relation || !counted[field])
+                continue;
+            const conditions = this.relationReadConditions(modelName, field, relation, userRole, user, 'select');
+            if (!conditions)
+                continue;
+            const entry = typeof counted[field] === 'object' ? counted[field] : {};
+            scoped = scoped ?? { ...counted };
+            scoped[field] = { ...entry, where: entry.where ? { AND: [entry.where, conditions] } : conditions };
+        }
+        if (!scoped)
+            return value;
+        return { ...(value === true ? {} : value), select: scoped };
+    }
+    /**
+     * Writes the rule's `set` values into every row of a write's `data`,
+     * overriding what the client sent (placeholders such as `$USER_ID` are
+     * resolved). Runs before the write is authorized, so the set values are
+     * checked like any other: against the create `conditions`, and a set
+     * foreign key against its `connect` rule.
+     */
+    applySetValues(modelName, userRole, data, user, action) {
+        const exposedModels = (exports.CorePrismaContext.getStore()?.exposedModels || []).map((m) => m.toLowerCase());
+        if (exposedModels.includes(modelName.toLowerCase()))
+            return;
+        const permissions = this.normalizedPermissionsConfig[modelName.toLowerCase()]?.[userRole] || {};
+        const set = this.selectPermission(permissions, action, modelName, userRole)?.set;
+        if (!set)
+            return;
+        const values = PrismaService_1._buildConditions(set, user);
+        for (const row of Array.isArray(data) ? data : [data]) {
+            if (row && typeof row === 'object')
+                Object.assign(row, values);
+        }
+    }
     /**
      * Enforces permission `conditions` on `create` / `createMany`.
      *
@@ -619,7 +883,7 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
             return;
         const conditions = actionPermissions.conditions;
         if (!conditions)
-            return; // permission defined but no conditions (e.g. setUserIdField only) → allow
+            return; // permission defined but no conditions (e.g. `set` only) → allow
         const condObj = Array.isArray(conditions) ? { AND: conditions } : conditions;
         const resolved = PrismaService_1._buildConditions(condObj, user);
         const data = params?.data;
@@ -700,6 +964,7 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
             const items = Array.isArray(value) ? value : [value];
             if (op === 'create') {
                 for (const child of items) {
+                    this.applySetValues(relatedModel, userRole, child, user, 'create');
                     await this.enforceCreateConditions(relatedModel, userRole, { data: child }, user, 'create', backFk);
                     await this.enforceNestedWrites(relatedModel, child, user, userRole, backFk);
                 }
@@ -928,7 +1193,7 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                         return false;
                     break;
                 default:
-                    throw new common_1.ForbiddenException(`create on ${modelName}: unsupported operator '${op}' on field '${key}' in a create condition. Use a simpler condition or setUserIdField.`);
+                    throw new common_1.ForbiddenException(`create on ${modelName}: unsupported operator '${op}' on field '${key}' in a create condition. Use a simpler condition or 'set'.`);
             }
         }
         return true;

package/docs/README.md

@@ -10,7 +10,9 @@ Authoritative usage documentation for `@appxdigital/appx-core`. **This folder is
 - **[data-access.md](./data-access.md)** — how you talk to the database: the Prisma proxy (`prisma.model.*`), how ABAC filtering and field omission are enforced on every call, the redirected single-record methods, relation behaviour, bypass hatches, and transactions.
 - **[authentication.md](./authentication.md)** — the built-in `/auth` surface, and **how to override framework internals** (extend the exported `AuthController`/`AuthService`/`RegisterDto`/Passport strategies and register your own at the same prefix via `AuthModule.forRoot({ controller: false })`) — e.g. adding `name` to registration.
 - **[graphql.md](./graphql.md)** — the **read-only** GraphQL API generated from your schema: queries, nested selections, and how ABAC filters them.
-- **[limitations.md](./limitations.md)** — **known limitations and features that are NOT ready for use** (e.g. `aggregate`, GraphQL writes). Read this before relying on any method not covered in the guides above.
+- **[testing.md](./testing.md)** — the test suite every new project ships with: `npm test` on a throwaway DB container, the HTTP harness (`api(actor)`, `registerActor`, raw `prisma`), and the route-sweep backstop.
+- **[storage.md](./storage.md)** — file uploads & object storage: the `setup:fileupload` wizard, per-endpoint size/MIME/role rules, and the S3 / GCS / local providers.
+- **[limitations.md](./limitations.md)** — **known limitations and features that are NOT ready for use** (e.g. `aggregate`). Read this before relying on any method not covered in the guides above.
 
 ## The one-paragraph mental model