@appxdigital/appx-core 0.1.120 → 0.1.121-beta.10

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

@@ -12,11 +12,45 @@ export type CorePrismaOptions = {
     BYPASS_OMISSION?: boolean;
     BYPASS_FILTERING?: boolean;
 };
-export type CorePrismaModel<M extends ModelKey> = Exclude<RuntimeClient[M], 'findUnique' | 'findUniqueOrThrow' | 'delete' | 'update'>;
+/** Look up a delegate method type without constraining the delegate `D`. */
+type MethodOf<D, K extends string> = K extends keyof D ? D[K] : never;
+/**
+ * Re-aligns a Prisma model delegate `D` to the proxy's real contract. Single-
+ * record methods that require a unique `where` can't carry the injected ABAC
+ * conditions, so each is re-aliased to its filter-compatible equivalent and the
+ * proxy transparently redirects the call at runtime:
+ *   - `findUnique` takes `findFirst`'s params/return; `findUniqueOrThrow` takes
+ *     `findFirstOrThrow`'s.
+ *   - `update` takes `updateMany`'s params and returns its result
+ *     (`BatchPayload`); `delete` takes `deleteMany`'s.
+ */
+export type ProxiedDelegate<D> = Omit<D, 'findUnique' | 'findUniqueOrThrow' | 'update' | 'delete'> & {
+    findUnique: MethodOf<D, 'findFirst'>;
+    findUniqueOrThrow: MethodOf<D, 'findFirstOrThrow'>;
+    update: MethodOf<D, 'updateMany'>;
+    delete: MethodOf<D, 'deleteMany'>;
+};
+export type CorePrismaModel<M extends ModelKey> = ProxiedDelegate<RuntimeClient[M]>;
+/**
+ * Applies {@link ProxiedDelegate} across every model delegate on a Prisma
+ * client, leaving non-delegate members (`$transaction`, `$connect`, …) intact.
+ */
+export type CorePrismaClient<C> = {
+    [K in keyof C]: C[K] extends {
+        findMany: (...args: any[]) => any;
+    } ? ProxiedDelegate<C[K]> : C[K];
+};
 export declare class PrismaService {
     private readonly permissionsConfig;
     private fieldConfigs;
     prismaClient: PrismaClient;
+    /**
+     * The un-proxied Prisma client. Used internally (e.g. create-condition
+     * checks) to look up an already-existing parent row without re-applying
+     * that model's access filtering — matching "would a findFirst with these
+     * conditions match".
+     */
+    private rawClient;
     constructor(prismaClient: PrismaClient, permissionsConfig: PermissionsConfigType);
     debugQueries(enable: boolean): void;
     withExposedModels(models: string[], callback: () => Promise<void>): Promise<void>;
@@ -29,7 +63,7 @@ export declare class PrismaService {
      * @param model
      */
     getModelDelegate<M extends ModelKey>(model: M): CorePrismaModel<M>;
-    get model(): RuntimeClient;
+    get model(): CorePrismaClient<RuntimeClient>;
     get user(): CorePrismaModel<'user'>;
     get session(): CorePrismaModel<'session'>;
     get userRefreshToken(): any;
@@ -62,6 +96,64 @@ export declare class PrismaService {
      * @throws ForbiddenException if no valid `where` conditions are present after applying permissions.
      */
     private applyWhereConditions;
+    /**
+     * Enforces permission `conditions` on `create` / `createMany`.
+     *
+     * Conditions cannot be pushed into a `WHERE` on insert, so instead we verify
+     * the incoming data *would* satisfy them — i.e. a `findFirst` with those
+     * conditions would return the new row. Own-scalar fields are checked against
+     * `data`; relation conditions are checked by looking up the referenced parent
+     * (which lets Prisma evaluate arbitrarily-nested relation conditions for us).
+     *
+     * Also default-denies: create is only allowed for a role/action that has an
+     * explicit permission (or 'ALL'), mirroring find/update/delete. Framework
+     * flows that must create without a permission (registration, sessions,
+     * tokens) pass BYPASS_FILTERING and never reach here.
+     *
+     * Fails **closed**: throws on a violation and on any condition shape it
+     * cannot evaluate, rather than silently allowing the insert.
+     */
+    private enforceCreateConditions;
+    /**
+     * Recursively authorizes nested relation writes in a `create` payload. Only
+     * an explicit allowlist of operators is permitted, each checked against ABAC;
+     * every other operator is rejected (fail closed).
+     *
+     * Runs on the create path only — `updateMany` / `createMany` (what update /
+     * createMany resolve to) accept scalar data, so nested relation writes reach
+     * Prisma solely via `create()`.
+     *
+     *   - `create` → the child must satisfy the related model's `create` rule
+     *     (recurses, so deeper nesting is authorized too).
+     *   - `connect` → the target must satisfy the related model's `connect` rule.
+     *     `connect` is a DEDICATED action: being allowed to READ a record does not
+     *     authorize associating it.
+     */
+    private enforceNestedWrites;
+    /** Authorizes each operator inside one relation's nested-write object. */
+    private enforceNestedRelationOps;
+    /** A `connect` requires an explicit `connect` permission on the target model. */
+    private assertConnectAllowed;
+    /**
+     * True only in an explicit local-development environment. Deliberately NOT
+     * `!== 'production'` — staging and other envs should behave like production
+     * (no extra diagnostic queries/logging). Only `development` / `dev` opt in.
+     */
+    private isDevMode;
+    /**
+     * Dev-only diagnostic. After a create that passed its create-conditions,
+     * checks whether the new row also satisfies the model's *find* conditions —
+     * if not, the creator can't read it back (create rule broader than find
+     * rule). Logs a warning; never affects the create. Runs only in development
+     * (gated by the caller).
+     */
+    private warnIfCreatedRowNotFindable;
+    /** Recursively evaluates a (placeholder-resolved) condition object against a to-be-created row. */
+    private matchesCreateConditions;
+    /** Evaluates a scalar-field condition (value or Prisma operator object) against the row's value. */
+    private matchesCreateScalar;
+    /** Verifies the parent referenced by a belongsTo condition exists and satisfies the nested condition. */
+    private matchesCreateRelation;
     /**
      * Builds dynamic conditions based on the type of clause (OR, AND, or field conditions).
      * Each condition is processed, and placeholders (like `$USER_ID`) are replaced with actual values.

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,EAAC,MAAM,yCAAyC,CAAC;AAE9E,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;AAGF,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,QAAQ,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,YAAY,GAAG,mBAAmB,GAAG,QAAQ,GAAG,QAAQ,CAAC,CAAC;AAEtI,qBACa,aAAa;IAMY,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IALpE,OAAO,CAAC,YAAY,CAA2B;IAC/C,YAAY,EAAE,YAAY,CAAC;gBAGvB,YAAY,EAAE,YAAY,EACqB,iBAAiB,EAAE,qBAAqB;IAO3F,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;IAuDX;;;;OAIG;IACH,gBAAgB,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;IAYlE,IAAI,KAAK,IAAI,aAAa,CAUzB;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;IAqDX;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAqC1B,IAAI,2BAA2B,QAM9B;IAED;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,oBAAoB;IA8K5B;;;;;;;OAOG;WACW,gBAAgB,CAAC,UAAU,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,GAAG,GAAG,GAAG;IAgBjE;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IA2BlC;;;;;;;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,UAAU,EAAE,OAAO,CAAA;KACtB;IAmBD,gBAAgB,CAAC,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAgBzF"}
+{"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;AAE/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;IAO3F,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;IA6EX;;;;OAIG;IACH,gBAAgB,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;IAYlE,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;IAqDX;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAkE1B,IAAI,2BAA2B,QAM9B;IAED;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,oBAAoB;IA8K5B;;;;;;;;;;;;;;;;OAgBG;YACW,uBAAuB;IAgDrC;;;;;;;;;;;;;;OAcG;YACW,mBAAmB;IAejC,0EAA0E;YAC5D,wBAAwB;IA+BtC,iFAAiF;YACnE,oBAAoB;IAkClC;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAKjB;;;;;;OAMG;YACW,2BAA2B;IAqBzC,mGAAmG;YACrF,uBAAuB;IAiCrC,oGAAoG;IACpG,OAAO,CAAC,mBAAmB;IAwB3B,yGAAyG;YAC3F,qBAAqB;IAuBnC;;;;;;;OAOG;WACW,gBAAgB,CAAC,UAAU,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,GAAG,GAAG,GAAG;IAgBjE;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IA2BlC;;;;;;;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,UAAU,EAAE,OAAO,CAAA;KACtB;IAmBD,gBAAgB,CAAC,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAyBzF"}

package/dist/prisma/prisma.service.js

@@ -16,6 +16,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PrismaService = exports.CorePrismaContext = void 0;
 const common_1 = require("@nestjs/common");
 const client_1 = require("@prisma/client");
+const permissionsConfigTypes_1 = require("../common/config/permissionsConfigTypes");
 const nestjs_request_context_1 = require("nestjs-request-context");
 const node_async_hooks_1 = require("node:async_hooks");
 exports.CorePrismaContext = new node_async_hooks_1.AsyncLocalStorage();
@@ -54,6 +55,10 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
         return this.prismaClient.$transaction(fn);
     }
     proxyModels() {
+        // Capture the un-proxied client before wrapping it (used by internal
+        // lookups that must bypass this proxy's access filtering — see
+        // enforceCreateConditions).
+        this.rawClient = this.prismaClient;
         // Proxy client to intercept model calls
         this.prismaClient = new Proxy(this.prismaClient, {
             get: (target, propKey) => {
@@ -68,16 +73,19 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                                 this.debug(`Proxying ${String(propKey)}.${String(methodKey)}() for role ${userRole}`);
                                 const contextModel = nestjs_request_context_1.RequestContext.currentContext?.req.prisma?.[propKey] || model;
                                 return async (params = {}, options) => {
-                                    // Blacklisted methods, should not be used to ensure permission filtering is applied
-                                    let blacklist = {
+                                    // Single-record methods can't carry the injected ABAC where-
+                                    // conditions, so redirect them to their filter-compatible
+                                    // equivalents. The proxied types remove/re-alias these, so this
+                                    // matches what a typed caller can express: update() runs
+                                    // updateMany, delete() runs deleteMany, and a findUnique lookup
+                                    // becomes a findFirst with conditions applied.
+                                    const redirect = {
                                         findUnique: 'findFirst',
                                         findUniqueOrThrow: 'findFirstOrThrow',
                                         delete: 'deleteMany',
                                         update: 'updateMany',
                                     };
-                                    if (blacklist[methodKey.toString()]) {
-                                        throw new Error(`The method ${methodKey.toString()} is not compatible with permission filtering and is not allowed. Please use ${blacklist[methodKey.toString()]}} instead.`);
-                                    }
+                                    methodKey = redirect[methodKey.toString()] ?? methodKey;
                                     // delete, deleteMany, update and updateMany methods should not apply field omission because they are not selecting fields
                                     if (!options?.BYPASS_OMISSION && !['delete', 'deleteMany', 'update', 'updateMany', 'create', 'createMany'].includes(methodKey.toString())) {
                                         params = this.applyFieldOmission(String(propKey), userRole, params);
@@ -85,8 +93,18 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                                     else {
                                         this.debug(`Skipping field omission for ${String(propKey)}.${String(methodKey)}()`);
                                     }
-                                    if (!options?.BYPASS_FILTERING && !['create', 'createMany'].includes(methodKey.toString())) {
-                                        params = this.applyWhereConditions(String(propKey), userRole, params, user, methodKey);
+                                    if (!options?.BYPASS_FILTERING) {
+                                        if (['create', 'createMany'].includes(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());
+                                            // Authorize any nested relation writes (create/connect) in
+                                            // the payload; reject every other nested operator.
+                                            await this.enforceNestedWrites(String(propKey), params.data, user, userRole);
+                                        }
+                                        else {
+                                            params = this.applyWhereConditions(String(propKey), userRole, params, user, methodKey);
+                                        }
                                     }
                                     else {
                                         this.debug(`Skipping permission filtering for ${String(propKey)}.${String(methodKey)}()`);
@@ -95,7 +113,14 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                                         delete params.select;
                                     }
                                     this.debug(`Executing ${String(propKey)}.${String(methodKey)}() with params: ${JSON.stringify(params)}`);
-                                    return contextModel[methodKey](params);
+                                    const result = await contextModel[methodKey](params);
+                                    // Dev-only: warn if a just-created row wouldn't be readable by its
+                                    // creator (create conditions broader than find conditions). Skipped
+                                    // outside development so no extra query runs on the hot path.
+                                    if (methodKey === 'create' && !options?.BYPASS_FILTERING && this.isDevMode()) {
+                                        await this.warnIfCreatedRowNotFindable(String(propKey), userRole, result);
+                                    }
+                                    return result;
                                 };
                             }
                             return model[methodKey];
@@ -208,6 +233,37 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
             omitFields.forEach((field) => {
                 delete args.select[field];
             });
+            // Omission must also apply to nested relation selections. Without this,
+            // a caller reads an omitted field on a RELATED model by nesting the
+            // request (e.g. `select: { rel: { select: { secret: true } } }`) — the
+            // top-level delete above only covers this model's own fields.
+            for (const key of Object.keys(args.select)) {
+                const relation = this.getRelation(modelName, key);
+                if (!relation) {
+                    continue; // scalar field (`true`) or `_count` — nothing to recurse
+                }
+                const relatedOmit = this.getFieldsToOmit(relation.model, userRole);
+                const value = args.select[key];
+                if (value === true) {
+                    // `rel: true` returns every scalar of the related model — narrow
+                    // it to the readable ones.
+                    args.select[key] = {
+                        select: this.buildSelectFields(relation.model, relatedOmit, null, null, userRole),
+                    };
+                }
+                else if (value && typeof value === 'object') {
+                    if (value.select || value.include) {
+                        // Recurse — strips the related model's omitted fields (and
+                        // deeper) while preserving any where/orderBy/take on `value`.
+                        args.select[key] = this.applyFieldOmission(relation.model, userRole, value);
+                    }
+                    else {
+                        // Relation args with no explicit projection (e.g. `{ where }`)
+                        // — inject a select that excludes omitted fields.
+                        value.select = this.buildSelectFields(relation.model, relatedOmit, null, null, userRole);
+                    }
+                }
+            }
         }
         else if (args.include) {
             this.debug(`Found included model '${modelName}', generating select fields`);
@@ -380,6 +436,272 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
         }
         return args;
     }
+    /**
+     * Enforces permission `conditions` on `create` / `createMany`.
+     *
+     * Conditions cannot be pushed into a `WHERE` on insert, so instead we verify
+     * the incoming data *would* satisfy them — i.e. a `findFirst` with those
+     * conditions would return the new row. Own-scalar fields are checked against
+     * `data`; relation conditions are checked by looking up the referenced parent
+     * (which lets Prisma evaluate arbitrarily-nested relation conditions for us).
+     *
+     * Also default-denies: create is only allowed for a role/action that has an
+     * explicit permission (or 'ALL'), mirroring find/update/delete. Framework
+     * flows that must create without a permission (registration, sessions,
+     * tokens) pass BYPASS_FILTERING and never reach here.
+     *
+     * Fails **closed**: throws on a violation and on any condition shape it
+     * cannot evaluate, rather than silently allowing the insert.
+     */
+    async enforceCreateConditions(modelName, userRole, params, user, action) {
+        const normalizedName = modelName.toLowerCase().trim();
+        const exposedModels = (exports.CorePrismaContext.getStore()?.exposedModels || []).map((m) => m.toLowerCase());
+        if (exposedModels.includes(normalizedName))
+            return;
+        const permissions = this.normalizedPermissionsConfig[normalizedName]?.[userRole];
+        if (!permissions) {
+            throw new common_1.HttpException(`No permissions defined for role ${userRole} on model '${modelName}' — create is denied by default. Define a '${action}' permission (or 'ALL').`, common_1.HttpStatus.FORBIDDEN);
+        }
+        const actionPermissions = permissions[action] ?? permissions['create'];
+        if (!actionPermissions) {
+            throw new common_1.HttpException(`Role ${userRole} has no '${action}' permission on model '${modelName}' — create is denied. Define it (or 'ALL').`, common_1.HttpStatus.FORBIDDEN);
+        }
+        if (actionPermissions === 'ALL')
+            return;
+        const conditions = actionPermissions.conditions;
+        if (!conditions)
+            return; // permission defined but no conditions (e.g. setUserIdField only) → allow
+        const condObj = Array.isArray(conditions) ? { AND: conditions } : conditions;
+        const resolved = PrismaService_1._buildConditions(condObj, user);
+        const data = params?.data;
+        const rows = Array.isArray(data) ? data : [data ?? {}];
+        for (const row of rows) {
+            const ok = await this.matchesCreateConditions(resolved, row || {}, modelName);
+            if (!ok) {
+                throw new common_1.ForbiddenException(`Not allowed to create ${modelName}: the record does not satisfy the '${action}' permission conditions for role ${userRole}.`);
+            }
+        }
+    }
+    /**
+     * Recursively authorizes nested relation writes in a `create` payload. Only
+     * an explicit allowlist of operators is permitted, each checked against ABAC;
+     * every other operator is rejected (fail closed).
+     *
+     * Runs on the create path only — `updateMany` / `createMany` (what update /
+     * createMany resolve to) accept scalar data, so nested relation writes reach
+     * Prisma solely via `create()`.
+     *
+     *   - `create` → the child must satisfy the related model's `create` rule
+     *     (recurses, so deeper nesting is authorized too).
+     *   - `connect` → the target must satisfy the related model's `connect` rule.
+     *     `connect` is a DEDICATED action: being allowed to READ a record does not
+     *     authorize associating it.
+     */
+    async enforceNestedWrites(modelName, data, user, userRole) {
+        if (!data || typeof data !== 'object')
+            return;
+        const rows = Array.isArray(data) ? data : [data];
+        for (const row of rows) {
+            if (!row || typeof row !== 'object')
+                continue;
+            for (const key of Object.keys(row)) {
+                const relation = this.getRelation(modelName, key);
+                if (!relation)
+                    continue; // scalar / FK field — not a relation nav key
+                const ops = row[key];
+                if (!ops || typeof ops !== 'object')
+                    continue;
+                await this.enforceNestedRelationOps(relation.model, key, ops, user, userRole, modelName);
+            }
+        }
+    }
+    /** Authorizes each operator inside one relation's nested-write object. */
+    async enforceNestedRelationOps(relatedModel, field, ops, user, userRole, parentModel) {
+        const ALLOWED = ['create', 'connect'];
+        for (const op of Object.keys(ops)) {
+            if (!ALLOWED.includes(op)) {
+                throw new common_1.ForbiddenException(`Nested '${op}' on relation '${field}' of ${parentModel} is not supported through the data-access proxy. ` +
+                    `Only ${ALLOWED.join(' / ')} are permitted; perform other nested writes in an explicit endpoint with its own authorization.`);
+            }
+            const value = ops[op];
+            const items = Array.isArray(value) ? value : [value];
+            if (op === 'create') {
+                for (const child of items) {
+                    await this.enforceCreateConditions(relatedModel, userRole, { data: child }, user, 'create');
+                    await this.enforceNestedWrites(relatedModel, child, user, userRole);
+                }
+            }
+            else {
+                for (const target of items) {
+                    await this.assertConnectAllowed(relatedModel, target, user, userRole, field);
+                }
+            }
+        }
+    }
+    /** A `connect` requires an explicit `connect` permission on the target model. */
+    async assertConnectAllowed(relatedModel, where, user, userRole, field) {
+        const normalizedName = relatedModel.toLowerCase().trim();
+        const exposedModels = (exports.CorePrismaContext.getStore()?.exposedModels || []).map((m) => m.toLowerCase());
+        if (exposedModels.includes(normalizedName))
+            return;
+        const connectPerm = this.normalizedPermissionsConfig[normalizedName]?.[userRole]?.['connect'];
+        if (!connectPerm) {
+            throw new common_1.ForbiddenException(`Not allowed to connect ${relatedModel} (via '${field}'): role ${userRole} has no 'connect' permission on ${relatedModel}.`);
+        }
+        if (connectPerm === 'ALL')
+            return;
+        const conditions = connectPerm.conditions;
+        const resolved = conditions
+            ? PrismaService_1._buildConditions(Array.isArray(conditions) ? { AND: conditions } : conditions, user)
+            : {};
+        const delegate = relatedModel.charAt(0).toLowerCase() + relatedModel.slice(1);
+        const client = nestjs_request_context_1.RequestContext.currentContext?.req.prisma || this.rawClient;
+        const found = await client[delegate].findFirst({ where: { AND: [where || {}, resolved] } });
+        if (!found) {
+            throw new common_1.ForbiddenException(`Not allowed to connect ${relatedModel} (via '${field}'): the target does not satisfy the 'connect' permission conditions for role ${userRole}.`);
+        }
+    }
+    /**
+     * True only in an explicit local-development environment. Deliberately NOT
+     * `!== 'production'` — staging and other envs should behave like production
+     * (no extra diagnostic queries/logging). Only `development` / `dev` opt in.
+     */
+    isDevMode() {
+        const env = process.env.NODE_ENV;
+        return env === 'development' || env === 'dev';
+    }
+    /**
+     * Dev-only diagnostic. After a create that passed its create-conditions,
+     * checks whether the new row also satisfies the model's *find* conditions —
+     * if not, the creator can't read it back (create rule broader than find
+     * rule). Logs a warning; never affects the create. Runs only in development
+     * (gated by the caller).
+     */
+    async warnIfCreatedRowNotFindable(modelKey, userRole, created) {
+        try {
+            if (!created || created.id === undefined || created.id === null)
+                return;
+            const permissions = this.normalizedPermissionsConfig[modelKey.toLowerCase()]?.[userRole];
+            const findPerm = permissions?.['findFirst'] ?? permissions?.['findMany'];
+            if (!findPerm || findPerm === 'ALL' || !findPerm.conditions)
+                return;
+            const found = await this.prismaClient[modelKey].findFirst({ where: { id: created.id } });
+            if (!found) {
+                console.warn('\x1b[33m', `[APPX-CORE PRISMA] Created ${modelKey} id=${created.id} as role ${userRole}, but it does not satisfy the model's find conditions — the creator cannot read it back. Ensure your find conditions are at least as permissive as your create conditions.`, '\x1b[0m');
+            }
+        }
+        catch {
+            // Dev diagnostic only — never let it affect the create.
+        }
+    }
+    /** Recursively evaluates a (placeholder-resolved) condition object against a to-be-created row. */
+    async matchesCreateConditions(cond, row, modelName) {
+        for (const key of Object.keys(cond)) {
+            const val = cond[key];
+            if (key === 'AND') {
+                const arr = Array.isArray(val) ? val : [val];
+                for (const c of arr)
+                    if (!(await this.matchesCreateConditions(c, row, modelName)))
+                        return false;
+                continue;
+            }
+            if (key === 'OR') {
+                const arr = Array.isArray(val) ? val : [val];
+                let any = false;
+                for (const c of arr)
+                    if (await this.matchesCreateConditions(c, row, modelName)) {
+                        any = true;
+                        break;
+                    }
+                if (!any)
+                    return false;
+                continue;
+            }
+            if (key === 'NOT') {
+                const arr = Array.isArray(val) ? val : [val];
+                for (const c of arr)
+                    if (await this.matchesCreateConditions(c, row, modelName))
+                        return false;
+                continue;
+            }
+            const relation = this.getRelation(modelName, key);
+            if (relation) {
+                if (!(await this.matchesCreateRelation(relation, key, val, row, modelName)))
+                    return false;
+                continue;
+            }
+            if (!this.matchesCreateScalar(row[key], val, key, modelName))
+                return false;
+        }
+        return true;
+    }
+    /** Evaluates a scalar-field condition (value or Prisma operator object) against the row's value. */
+    matchesCreateScalar(actual, cond, key, modelName) {
+        if (cond === null)
+            return actual === null || actual === undefined;
+        if (cond instanceof Date || typeof cond !== 'object')
+            return actual === cond;
+        for (const op of Object.keys(cond)) {
+            const opv = cond[op];
+            switch (op) {
+                case 'equals':
+                    if (actual !== opv)
+                        return false;
+                    break;
+                case 'not':
+                    if (actual === opv)
+                        return false;
+                    break;
+                case 'in':
+                    if (!Array.isArray(opv) || !opv.includes(actual))
+                        return false;
+                    break;
+                case 'notIn':
+                    if (Array.isArray(opv) && opv.includes(actual))
+                        return false;
+                    break;
+                case 'lt':
+                    if (!(actual < opv))
+                        return false;
+                    break;
+                case 'lte':
+                    if (!(actual <= opv))
+                        return false;
+                    break;
+                case 'gt':
+                    if (!(actual > opv))
+                        return false;
+                    break;
+                case 'gte':
+                    if (!(actual >= opv))
+                        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.`);
+            }
+        }
+        return true;
+    }
+    /** Verifies the parent referenced by a belongsTo condition exists and satisfies the nested condition. */
+    async matchesCreateRelation(relation, field, nestedCond, row, modelName) {
+        if (relation.relation !== 'belongsTo' || !relation.referencingColumn) {
+            throw new common_1.ForbiddenException(`create on ${modelName}: unsupported relation condition on '${field}' — a new row has no related '${field}' yet to match. Constrain the scalar foreign key instead.`);
+        }
+        const fkValue = row[relation.referencingColumn];
+        if (fkValue === undefined || fkValue === null)
+            return false;
+        const delegate = relation.model.charAt(0).toLowerCase() + relation.model.slice(1);
+        // Use the request's transaction client if present (to see rows created
+        // earlier in the same request), else the raw client. Either way, access
+        // filtering on the parent is intentionally NOT re-applied — we check
+        // only the condition.
+        const client = nestjs_request_context_1.RequestContext.currentContext?.req.prisma || this.rawClient;
+        const found = await client[delegate].findFirst({
+            where: { AND: [{ [relation.foreignKey]: fkValue }, nestedCond] },
+            select: { [relation.foreignKey]: true },
+        });
+        return !!found;
+    }
     /**
      * Builds dynamic conditions based on the type of clause (OR, AND, or field conditions).
      * Each condition is processed, and placeholders (like `$USER_ID`) are replaced with actual values.
@@ -532,6 +854,14 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                 actionPermissions = permissions['findFirst'];
             }
         }
+        // A `*Many` action inherits the singular rule when not set explicitly
+        // (updateMany → update, deleteMany → delete). `update()` / `delete()`
+        // redirect to their `*Many` form, so this is what makes a config that
+        // declares only `update` / `delete` apply to them.
+        if (!actionPermissions && permissionsConfigTypes_1.SINGULAR_ACTION[action] && permissions[permissionsConfigTypes_1.SINGULAR_ACTION[action]]) {
+            this.debug(`Using '${permissionsConfigTypes_1.SINGULAR_ACTION[action]}' permissions for '${action}' action on model '${modelName}' and role ${userRole}`, 'info');
+            actionPermissions = permissions[permissionsConfigTypes_1.SINGULAR_ACTION[action]];
+        }
         return actionPermissions;
     }
 };

package/docs/README.md

@@ -0,0 +1,21 @@
+# AppX Core — Documentation
+
+Authoritative usage documentation for `@appxdigital/appx-core`. **This folder is the source of truth** for how the framework behaves — humans and AI agents should read it here rather than inferring patterns from source code. If code and these docs disagree, that is a bug in one of them; fix it, don't guess.
+
+## Contents
+
+- **[permissions.md](./permissions.md)** — the authorization model: the `@Permission` and `@ExposeModels` decorators, the `permissions.config.ts` shape, roles/actions, row-level `conditions`, field-level control, action fallbacks, and the `GUEST` (unauthenticated) flow.
+- **[dtos.md](./dtos.md)** — the generated CRUD validation DTOs: their two-file structure, **how to remove a field** (`OmitType` / `@NoWrite` / `restrictedFields`), how to add validation, and why nested relation writes don't belong on generic CRUD.
+- **[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.
+- **[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.
+
+## The one-paragraph mental model
+
+AppX Core wraps the Prisma client in a proxy that enforces **attribute-based access control (ABAC)** on every database call. You declare row-level and field-level rules once in `permissions.config.ts`; the proxy injects them into each query automatically based on the current request's user role. Controllers/resolvers are generated from your Prisma schema. The rules of the road: **go through the proxy** (`prismaService.model.*`) so ABAC applies, **declare a permission for every model/role/action** you want to allow (everything else is default-denied), and **check [limitations.md](./limitations.md)** before using a method.
+
+## Conventions used in these docs
+
+- `$USER_ID` refers to `PermissionPlaceholder.USER_ID` — a placeholder replaced with the current user's id at query time.
+- "the proxy" means the `PrismaService` client returned by `prismaService.model` (and the `prisma.user` / `prisma.session` / `prisma.userRefreshToken` accessors).
+- "default-deny" means: if no rule matches, the request is refused (a `403` at the guard, or a thrown `HttpException` at the proxy) — never silently allowed.