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

package/CHANGELOG.md

@@ -117,6 +117,19 @@ async update(@Param('id') id: string, @Body() data: Update<Model>Dto) { return s
 >
 > **For AI agents doing this migration on an existing project:** this can break existing behaviour. Before deploying, tell the developer explicitly that (a) any nested operator other than `create`/`connect` used through CRUD will now `400`, (b) every model that is nested-`connect`ed now needs a `connect` permission or the request fails, and (c) nested writes no longer work on update endpoints. Do not proceed silently. See [`docs/dtos.md`](../docs/dtos.md#relations--nested-writes) and [`docs/permissions.md`](../docs/permissions.md).
 
+> ## ⚠️ Relationship authorization moved to `connect` — this WILL break configs; the app refuses to boot until migrated
+>
+> **Every foreign-key reference a `create` establishes is now authorized by the target model's `connect` rule** — whether supplied as a nested `connect`, a nested `create`, **or a plain scalar foreign key** (`ownerId: 7` is checked against `User.connect`, no bypass). A **`create` condition now judges the created model's own scalar fields only** — it must NOT reach across a relation. The one thing not re-checked is the foreign key Prisma auto-fills for a child nested inside its parent's `create` (the parent already authorized itself).
+>
+> **The framework validates this at boot.** If a model a role can `create` has a **required** foreign key whose target has **no `connect` rule** for that role, **the app refuses to start** (it would always `403`); an optional FK logs a warning; a `create` condition that references a relation is also a boot error.
+>
+> **Required migration for existing projects:**
+> 1. **Move relationship checks out of `create` conditions and into `connect` rules.** A rule like `ExamQuestion.create: { conditions: { exam: { course: {...} } } }` must become `Course.connect: { conditions: {...} }` (or `Exam.connect`), reached via the FK on the create. A `create` condition may only constrain the model's **own** columns (e.g. `{ ownerId: $USER_ID }`, which stays valid and is still checked).
+> 2. **Add a `connect` rule to every model referenced by a foreign key on a create you allow.** For unrestricted roles that already have `create: 'ALL'`, add `connect: 'ALL'`. Start the app — the boot error lists every missing `<Model>.<Role>.connect` by name; add each until it starts.
+> 3. Because one `connect` rule serves every relation that points at a model (it is keyed on `[model][role]`, not per-relation), make its conditions the **union** of what any referencing relation legitimately needs; enforce anything finer in an explicit endpoint.
+>
+> **For AI agents:** this is a behaviour restriction on a production app. Before deploying, tell the developer that (a) any create that sets a foreign key to a model without a `connect` rule now fails — and the app won't boot until those rules exist, and (b) any `create` condition that referenced a relation no longer enforces it there and must be re-expressed as a `connect` rule. Do not proceed silently. The boot-time error message names exactly what to add. See [`docs/permissions.md`](../docs/permissions.md#the-connect-action--authorizes-every-relationship-a-create-establishes).
+
 **5. Create-permission enforcement (behaviour change — review before upgrading).**
 - Ensure every model/role that legitimately creates records has an explicit `create` permission (or `'ALL'`). Without one, create now returns `403` (previously unchecked). Internal framework flows (registration, sessions, tokens) are unaffected.
 - If you supplied arbitrary values for a field a `create` condition constrains (e.g. an owner id), those requests now return `403` unless the value matches — use `setUserIdField` to have the framework set it.

package/PRERELEASES.md

@@ -31,6 +31,24 @@ Prereleases are excluded from normal semver range resolution, so a project on
 
 ---
 
+## [0.1.121-beta.12] — unreleased
+
+**Library.** **Relationship authorization moved entirely to the `connect` action, with boot-time config validation.** Two fixes from an adopter report plus the model change:
+
+- **Fix — create condition vs the `connect` form.** A create condition on a scalar FK (`{ ownerId: $USER_ID }`) is now satisfied when the association is supplied via `owner: { connect: { id } }`, not only the raw scalar. Resolved from relation metadata (no naming assumptions).
+- **Model change (behaviour restriction — review on upgrade).** A `create` condition judges the model's **own scalar fields only**; **every foreign-key reference a create establishes — raw scalar FK, `connect`, or nested `create` — is authorized by the target model's `connect` rule** (default-deny, no bypass). The auto-filled back-FK to a same-request nesting parent is trusted. This fixes nested `create`s whose child rule referenced the parent (previously a spurious `403`) and closes the raw-FK bypass.
+- **Boot validation.** The config is checked against the schema at startup: a required FK whose target has no `connect` rule for a creating role, or a `create` condition that references a relation, **rejects boot** (optional FK → warning). The error names each missing `<Model>.<Role>.connect`.
+- **Migration is mandatory** — see the `[0.1.121]` banner in `CHANGELOG.md` (“Relationship authorization moved to `connect`”). Move relation-reaching create conditions to `connect` rules and add a `connect` rule for every FK-referenced model. An agent doing the migration must warn the developer.
+
+## [0.1.121-beta.11] — unreleased
+
+**Docs.** No code change. Documented that nested writes over HTTP CRUD are
+**one level deep** (a nested `create` DTO exposes the related model's scalars +
+`connect`, not its own relations, to avoid circular DTOs). The proxy's
+authorization is recursive; the DTO surface is the cap — deeper nesting `400`s,
+and multi-level nested writes belong in an explicit endpoint. See `docs/dtos.md`
+and `docs/limitations.md`.
+
 ## [0.1.121-beta.10] — unreleased
 
 **Library.** **Nested relation writes on generated CRUD are now an explicit,

package/dist/prisma/permissions-validator.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Static validation of a `PermissionsConfig` against the Prisma schema.
+ *
+ * Runs at boot (in the PrismaService constructor). It encodes the Option A
+ * authorization model: a create condition judges a model's own scalar fields
+ * only, and every foreign-key reference a create establishes is authorized by
+ * the target model's `connect` rule. Misconfigurations that would break at
+ * runtime are surfaced here — errors reject boot, warnings are advisory.
+ *
+ * Pure and schema-only (no database), so it is independently unit-testable.
+ */
+export type RelationKind = 'belongsTo' | 'hasMany';
+export interface RelationMeta {
+    /** The relation navigation field name on the owning model. */
+    field: string;
+    /** The target model name (original casing, as in the schema). */
+    model: string;
+    /** The owning model's scalar FK column (belongsTo only). */
+    referencingColumn?: string;
+    isRequired: boolean;
+    kind: RelationKind;
+}
+/** Relations per model, keyed by the lower-cased model name. */
+export type SchemaRelations = Record<string, RelationMeta[]>;
+export type IssueLevel = 'error' | 'warning';
+export type IssueCode = 'relation-in-create-condition' | 'missing-connect-required' | 'missing-connect-optional';
+export interface ValidationIssue {
+    level: IssueLevel;
+    code: IssueCode;
+    model: string;
+    role: string;
+    message: string;
+}
+/**
+ * Validates the permissions config against the schema relations.
+ *
+ * Checks, per model + role that can create the model:
+ *  - **error** `relation-in-create-condition` — a create condition references a
+ *    relation. Create conditions are own-scalar-only; relationship checks belong
+ *    on the target's `connect` rule.
+ *  - **error** `missing-connect-required` — a *required* belongsTo FK's target
+ *    has no `connect` rule for the role. Every create sets it, so it will always
+ *    be denied at runtime.
+ *  - **warning** `missing-connect-optional` — an *optional* belongsTo FK's target
+ *    has no `connect` rule for the role. Only denied when the payload sets it.
+ */
+export declare function validatePermissionsConfig(config: Record<string, Record<string, any>>, relations: SchemaRelations): ValidationIssue[];
+//# sourceMappingURL=permissions-validator.d.ts.map

package/dist/prisma/permissions-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions-validator.d.ts","sourceRoot":"","sources":["../../src/prisma/permissions-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,SAAS,CAAC;AAEnD,MAAM,WAAW,YAAY;IACzB,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,YAAY,CAAC;CACtB;AAED,gEAAgE;AAChE,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;AAE7D,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;AAE7C,MAAM,MAAM,SAAS,GACf,8BAA8B,GAC9B,0BAA0B,GAC1B,0BAA0B,CAAC;AAEjC,MAAM,WAAW,eAAe;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACnB;AAmBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,EAC3C,SAAS,EAAE,eAAe,GAC3B,eAAe,EAAE,CA8DnB"}

package/dist/prisma/permissions-validator.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Static validation of a `PermissionsConfig` against the Prisma schema.
+ *
+ * Runs at boot (in the PrismaService constructor). It encodes the Option A
+ * authorization model: a create condition judges a model's own scalar fields
+ * only, and every foreign-key reference a create establishes is authorized by
+ * the target model's `connect` rule. Misconfigurations that would break at
+ * runtime are surfaced here — errors reject boot, warnings are advisory.
+ *
+ * Pure and schema-only (no database), so it is independently unit-testable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePermissionsConfig = void 0;
+/** Collects condition keys that name a relation (skips AND/OR/NOT, which recurse). */
+function findRelationKeys(cond, relationFields, found = new Set()) {
+    if (!cond || typeof cond !== 'object')
+        return found;
+    const objs = Array.isArray(cond) ? cond : [cond];
+    for (const obj of objs) {
+        if (!obj || typeof obj !== 'object')
+            continue;
+        for (const key of Object.keys(obj)) {
+            if (key === 'AND' || key === 'OR' || key === 'NOT') {
+                findRelationKeys(obj[key], relationFields, found);
+                continue;
+            }
+            if (relationFields.has(key))
+                found.add(key);
+        }
+    }
+    return found;
+}
+/**
+ * Validates the permissions config against the schema relations.
+ *
+ * Checks, per model + role that can create the model:
+ *  - **error** `relation-in-create-condition` — a create condition references a
+ *    relation. Create conditions are own-scalar-only; relationship checks belong
+ *    on the target's `connect` rule.
+ *  - **error** `missing-connect-required` — a *required* belongsTo FK's target
+ *    has no `connect` rule for the role. Every create sets it, so it will always
+ *    be denied at runtime.
+ *  - **warning** `missing-connect-optional` — an *optional* belongsTo FK's target
+ *    has no `connect` rule for the role. Only denied when the payload sets it.
+ */
+function validatePermissionsConfig(config, relations) {
+    const issues = [];
+    const byModel = {};
+    for (const m of Object.keys(config || {}))
+        byModel[m.toLowerCase()] = config[m];
+    const hasConnectRule = (targetModel, role) => {
+        const rules = byModel[targetModel.toLowerCase()]?.[role];
+        return !!rules && rules.connect !== undefined && rules.connect !== null;
+    };
+    const canCreate = (rules) => !!rules && (rules.create !== undefined || rules.createMany !== undefined);
+    for (const modelKey of Object.keys(config || {})) {
+        const roles = config[modelKey] || {};
+        const rels = relations[modelKey.toLowerCase()] || [];
+        const belongsTo = rels.filter((r) => r.kind === 'belongsTo' && r.referencingColumn);
+        const relationFieldNames = new Set(rels.map((r) => r.field));
+        for (const role of Object.keys(roles)) {
+            const rules = roles[role];
+            if (!canCreate(rules))
+                continue;
+            const createRule = rules.create ?? rules.createMany;
+            const conditions = createRule && typeof createRule === 'object' ? createRule.conditions : undefined;
+            if (conditions) {
+                for (const relField of findRelationKeys(conditions, relationFieldNames)) {
+                    issues.push({
+                        level: 'error',
+                        code: 'relation-in-create-condition',
+                        model: modelKey,
+                        role,
+                        message: `create condition on ${modelKey}.${role} references relation '${relField}'. Create conditions judge own scalar fields only — authorize relationships with the target model's 'connect' rule.`,
+                    });
+                }
+            }
+            for (const r of belongsTo) {
+                if (hasConnectRule(r.model, role))
+                    continue;
+                if (r.isRequired) {
+                    issues.push({
+                        level: 'error',
+                        code: 'missing-connect-required',
+                        model: modelKey,
+                        role,
+                        message: `${modelKey}.${role} can create, but its required foreign key '${r.referencingColumn}' → ${r.model} has no 'connect' rule for ${role}. Every create sets it, so the create is always denied. Declare '${r.model}.${role}.connect' (or 'ALL').`,
+                    });
+                }
+                else {
+                    issues.push({
+                        level: 'warning',
+                        code: 'missing-connect-optional',
+                        model: modelKey,
+                        role,
+                        message: `${modelKey}.${role} can create and its optional foreign key '${r.referencingColumn}' → ${r.model} has no 'connect' rule for ${role}. A payload that sets it is denied. Declare '${r.model}.${role}.connect' if that association is expected.`,
+                    });
+                }
+            }
+        }
+    }
+    return issues;
+}
+exports.validatePermissionsConfig = validatePermissionsConfig;

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

@@ -52,6 +52,13 @@ export declare class PrismaService {
      */
     private rawClient;
     constructor(prismaClient: PrismaClient, permissionsConfig: PermissionsConfigType);
+    /**
+     * Validates the permissions config against the schema at boot. Warnings are
+     * logged; errors (a create condition that crosses a relation, or a required
+     * FK whose target has no `connect` rule) reject boot — the misconfiguration
+     * would otherwise surface as a runtime 403.
+     */
+    private validatePermissions;
     debugQueries(enable: boolean): void;
     withExposedModels(models: string[], callback: () => Promise<void>): Promise<void>;
     private debug;
@@ -115,23 +122,32 @@ export declare class PrismaService {
      */
     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).
+     * Authorizes every relation a `create` payload establishes. Relationship
+     * authorization lives entirely in the `connect` action — create conditions
+     * judge a model's own scalar fields only.
      *
      * 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()`.
+     * createMany resolve to) accept scalar data, so 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.
+     *   - A raw scalar foreign key (`courseId: 7`) → the target's `connect` rule.
+     *   - `relation: { connect }` → the target's `connect` rule. `connect` is a
+     *     DEDICATED action: being allowed to READ a record does not authorize
+     *     associating it.
+     *   - `relation: { create }` → the target's `create` rule (recurses, so deeper
+     *     nesting is authorized too). Every other nested operator is rejected.
+     *
+     * The one exception is `trustedFk`: the scalar FK that points back to the row
+     * we're nested under. Prisma fills it at write time and the parent already
+     * authorized itself, so it is not re-checked.
      */
     private enforceNestedWrites;
     /** Authorizes each operator inside one relation's nested-write object. */
     private enforceNestedRelationOps;
+    /** If `column` is the scalar FK backing a belongsTo relation, returns that relation's target. */
+    private foreignKeyColumn;
+    /** The child's scalar FK column pointing back to the parent it's nested under (trusted). */
+    private backReferenceFk;
     /** A `connect` requires an explicit `connect` permission on the target model. */
     private assertConnectAllowed;
     /**
@@ -148,12 +164,25 @@ export declare class PrismaService {
      * (gated by the caller).
      */
     private warnIfCreatedRowNotFindable;
-    /** Recursively evaluates a (placeholder-resolved) condition object against a to-be-created row. */
+    /**
+     * A view of a create `row` where a belongsTo relation given via `connect`
+     * (`owner: { connect: { id } }`) is also surfaced as its scalar FK (`ownerId`),
+     * so scalar-FK create conditions match either payload form. Metadata-driven
+     * (`referencingColumn`/`foreignKey`); resolvable only when the connect targets
+     * the referenced column. Explicit scalar wins; row is not mutated.
+     */
+    private resolveConnectForeignKeys;
+    /**
+     * Evaluates a (placeholder-resolved) create condition against a to-be-created
+     * row. Create conditions judge the model's OWN scalar fields only — a clause
+     * that reaches into a relation is not a create concern (relationships are
+     * authorized by the target's `connect` rule) and is skipped here; the config
+     * validator rejects such clauses at boot. `trustedFk` (the back-reference to a
+     * same-request nesting parent) is likewise skipped — its value doesn't exist yet.
+     */
     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.
@@ -198,6 +227,7 @@ export declare class PrismaService {
         relation: string;
         foreignKey?: string;
         referencingColumn?: string;
+        relationName?: string;
         isRequired: boolean;
     };
     selectPermission(permissions: any, action: string, modelName: string, userRole: string): any;

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":"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"}
+{"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

@@ -17,6 +17,7 @@ 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 permissions_validator_1 = require("./permissions-validator");
 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();
@@ -26,8 +27,37 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
         this.fieldConfigs = {};
         this.prismaClient = prismaClient;
         this.parseSchema();
+        this.validatePermissions();
         this.proxyModels();
     }
+    /**
+     * Validates the permissions config against the schema at boot. Warnings are
+     * logged; errors (a create condition that crosses a relation, or a required
+     * FK whose target has no `connect` rule) reject boot — the misconfiguration
+     * would otherwise surface as a runtime 403.
+     */
+    validatePermissions() {
+        const relations = {};
+        for (const model of Object.keys(this.fieldConfigs)) {
+            const relationFields = this.fieldConfigs[model].relationFields || {};
+            relations[model] = Object.keys(relationFields).map((field) => ({
+                field,
+                model: relationFields[field].model,
+                referencingColumn: relationFields[field].referencingColumn,
+                isRequired: relationFields[field].isRequired,
+                kind: relationFields[field].relation,
+            }));
+        }
+        const issues = (0, permissions_validator_1.validatePermissionsConfig)(this.permissionsConfig, relations);
+        for (const issue of issues.filter((i) => i.level === 'warning')) {
+            console.warn('\x1b[33m', `[APPX-CORE PERMISSIONS] ${issue.message}`, '\x1b[0m');
+        }
+        const errors = issues.filter((i) => i.level === 'error');
+        if (errors.length) {
+            throw new Error(`[APPX-CORE PERMISSIONS] Invalid permissions configuration — ${errors.length} error(s):\n` +
+                errors.map((e) => `  • ${e.message}`).join('\n'));
+        }
+    }
     debugQueries(enable) {
         nestjs_request_context_1.RequestContext.currentContext.req.corePrismaDebug = enable;
     }
@@ -198,6 +228,10 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                         model: field.type,
                         relation: field.isList ? 'hasMany' : 'belongsTo',
                         isRequired: field.isRequired,
+                        // Disambiguates multiple relations between the same two models
+                        // (e.g. Task.assignee / Task.reviewer, self-relations) so the
+                        // inverse (back-reference) side can be paired reliably.
+                        relationName: field.relationName,
                     };
                     if (!field.isList && field.relationToFields && field.relationFromFields) {
                         relationFields[field_name].foreignKey = field.relationToFields[0];
@@ -453,7 +487,7 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
      * 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) {
+    async enforceCreateConditions(modelName, userRole, params, user, action, trustedFk) {
         const normalizedName = modelName.toLowerCase().trim();
         const exposedModels = (exports.CorePrismaContext.getStore()?.exposedModels || []).map((m) => m.toLowerCase());
         if (exposedModels.includes(normalizedName))
@@ -476,28 +510,34 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
         const data = params?.data;
         const rows = Array.isArray(data) ? data : [data ?? {}];
         for (const row of rows) {
-            const ok = await this.matchesCreateConditions(resolved, row || {}, modelName);
+            const effectiveRow = this.resolveConnectForeignKeys(modelName, row || {});
+            const ok = await this.matchesCreateConditions(resolved, effectiveRow, modelName, trustedFk);
             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).
+     * Authorizes every relation a `create` payload establishes. Relationship
+     * authorization lives entirely in the `connect` action — create conditions
+     * judge a model's own scalar fields only.
      *
      * 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()`.
+     * createMany resolve to) accept scalar data, so 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.
+     *   - A raw scalar foreign key (`courseId: 7`) → the target's `connect` rule.
+     *   - `relation: { connect }` → the target's `connect` rule. `connect` is a
+     *     DEDICATED action: being allowed to READ a record does not authorize
+     *     associating it.
+     *   - `relation: { create }` → the target's `create` rule (recurses, so deeper
+     *     nesting is authorized too). Every other nested operator is rejected.
+     *
+     * The one exception is `trustedFk`: the scalar FK that points back to the row
+     * we're nested under. Prisma fills it at write time and the parent already
+     * authorized itself, so it is not re-checked.
      */
-    async enforceNestedWrites(modelName, data, user, userRole) {
+    async enforceNestedWrites(modelName, data, user, userRole, trustedFk) {
         if (!data || typeof data !== 'object')
             return;
         const rows = Array.isArray(data) ? data : [data];
@@ -506,18 +546,34 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                 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')
+                if (relation) {
+                    const ops = row[key];
+                    if (!ops || typeof ops !== 'object')
+                        continue; // e.g. an explicit `null` disconnect-by-omission
+                    await this.enforceNestedRelationOps(relation.model, key, ops, user, userRole, modelName, relation.relationName);
+                    continue;
+                }
+                // A plain scalar that happens to be a belongsTo foreign key still
+                // establishes an association — authorize it against the target's
+                // `connect` rule, exactly as the `connect` form would be.
+                const fk = this.foreignKeyColumn(modelName, key);
+                if (!fk)
+                    continue; // ordinary scalar
+                if (key === trustedFk)
+                    continue; // back-reference to the nesting parent — trusted
+                const value = row[key];
+                if (value === undefined || value === null)
                     continue;
-                await this.enforceNestedRelationOps(relation.model, key, ops, user, userRole, modelName);
+                await this.assertConnectAllowed(fk.model, { [fk.foreignKey]: value }, user, userRole, key);
             }
         }
     }
     /** Authorizes each operator inside one relation's nested-write object. */
-    async enforceNestedRelationOps(relatedModel, field, ops, user, userRole, parentModel) {
+    async enforceNestedRelationOps(relatedModel, field, ops, user, userRole, parentModel, parentRelationName) {
         const ALLOWED = ['create', 'connect'];
+        // The child's FK back to the parent it's nested under is filled by Prisma
+        // and trusted; skip it when authorizing the child's own relations.
+        const backFk = this.backReferenceFk(relatedModel, parentModel, parentRelationName);
         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. ` +
@@ -527,8 +583,8 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
             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);
+                    await this.enforceCreateConditions(relatedModel, userRole, { data: child }, user, 'create', backFk);
+                    await this.enforceNestedWrites(relatedModel, child, user, userRole, backFk);
                 }
             }
             else {
@@ -538,6 +594,32 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
             }
         }
     }
+    /** If `column` is the scalar FK backing a belongsTo relation, returns that relation's target. */
+    foreignKeyColumn(modelName, column) {
+        const rels = this.fieldConfigs[modelName.toLowerCase()]?.relationFields || {};
+        for (const key of Object.keys(rels)) {
+            const r = rels[key];
+            if (r.relation === 'belongsTo' && r.referencingColumn === column && r.foreignKey) {
+                return { model: r.model, foreignKey: r.foreignKey, relationName: r.relationName };
+            }
+        }
+        return null;
+    }
+    /** The child's scalar FK column pointing back to the parent it's nested under (trusted). */
+    backReferenceFk(childModel, parentModel, parentRelationName) {
+        const rels = this.fieldConfigs[childModel.toLowerCase()]?.relationFields || {};
+        const candidates = Object.keys(rels)
+            .map(key => rels[key])
+            .filter((r) => r.relation === 'belongsTo' && r.referencingColumn && r.model.toLowerCase() === parentModel.toLowerCase());
+        // Prisma pairs the two sides of a relation by `relationName`; use it to
+        // disambiguate when the child has several relations to the same parent.
+        if (parentRelationName) {
+            const exact = candidates.find((r) => r.relationName === parentRelationName);
+            if (exact)
+                return exact.referencingColumn;
+        }
+        return candidates.length === 1 ? candidates[0].referencingColumn : undefined;
+    }
     /** A `connect` requires an explicit `connect` permission on the target model. */
     async assertConnectAllowed(relatedModel, where, user, userRole, field) {
         const normalizedName = relatedModel.toLowerCase().trim();
@@ -594,14 +676,50 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
             // 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) {
+    /**
+     * A view of a create `row` where a belongsTo relation given via `connect`
+     * (`owner: { connect: { id } }`) is also surfaced as its scalar FK (`ownerId`),
+     * so scalar-FK create conditions match either payload form. Metadata-driven
+     * (`referencingColumn`/`foreignKey`); resolvable only when the connect targets
+     * the referenced column. Explicit scalar wins; row is not mutated.
+     */
+    resolveConnectForeignKeys(modelName, row) {
+        if (!row || typeof row !== 'object')
+            return row;
+        let effective = row;
+        for (const key of Object.keys(row)) {
+            const relation = this.getRelation(modelName, key);
+            if (!relation || relation.relation !== 'belongsTo')
+                continue;
+            if (!relation.referencingColumn || !relation.foreignKey)
+                continue;
+            if (row[relation.referencingColumn] !== undefined)
+                continue; // explicit scalar wins
+            const connectWhere = row[key]?.connect;
+            const fk = connectWhere?.[relation.foreignKey];
+            if (fk === undefined)
+                continue;
+            if (effective === row)
+                effective = { ...row };
+            effective[relation.referencingColumn] = fk;
+        }
+        return effective;
+    }
+    /**
+     * Evaluates a (placeholder-resolved) create condition against a to-be-created
+     * row. Create conditions judge the model's OWN scalar fields only — a clause
+     * that reaches into a relation is not a create concern (relationships are
+     * authorized by the target's `connect` rule) and is skipped here; the config
+     * validator rejects such clauses at boot. `trustedFk` (the back-reference to a
+     * same-request nesting parent) is likewise skipped — its value doesn't exist yet.
+     */
+    async matchesCreateConditions(cond, row, modelName, trustedFk) {
         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)))
+                    if (!(await this.matchesCreateConditions(c, row, modelName, trustedFk)))
                         return false;
                 continue;
             }
@@ -609,7 +727,7 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                 const arr = Array.isArray(val) ? val : [val];
                 let any = false;
                 for (const c of arr)
-                    if (await this.matchesCreateConditions(c, row, modelName)) {
+                    if (await this.matchesCreateConditions(c, row, modelName, trustedFk)) {
                         any = true;
                         break;
                     }
@@ -620,16 +738,14 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
             if (key === 'NOT') {
                 const arr = Array.isArray(val) ? val : [val];
                 for (const c of arr)
-                    if (await this.matchesCreateConditions(c, row, modelName))
+                    if (await this.matchesCreateConditions(c, row, modelName, trustedFk))
                         return false;
                 continue;
             }
-            const relation = this.getRelation(modelName, key);
-            if (relation) {
-                if (!(await this.matchesCreateRelation(relation, key, val, row, modelName)))
-                    return false;
-                continue;
-            }
+            if (key === trustedFk)
+                continue; // parent link, filled by Prisma — trusted
+            if (this.getRelation(modelName, key))
+                continue; // relation clause — authorized via `connect`, not here
             if (!this.matchesCreateScalar(row[key], val, key, modelName))
                 return false;
         }
@@ -682,26 +798,6 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
         }
         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.

package/docs/dtos.md

@@ -124,6 +124,8 @@ Generated **create** DTOs expose each relation as a nested-write member that acc
 
 So a nested write succeeds only when it is an allowed operator **and** the caller passes the related model's rule.
 
+**Raw foreign keys are authorized the same way.** Setting a relation by its scalar FK (`ownerId: 7`) instead of `owner: { connect: { id: 7 } }` is not a shortcut around authorization — the framework knows `ownerId` backs the `owner` relation and checks the value against `User.connect` exactly as the `connect` form would. Every foreign key a create establishes needs a `connect` rule on its target (the sole exception is the FK Prisma fills for a child nested inside its parent, which is trusted). If a required FK's target has no `connect` rule, the app refuses to boot. See [permissions.md](./permissions.md#the-connect-action--authorizes-every-relationship-a-create-establishes).
+
 **Only `create()` carries nested writes.** `update` resolves to `updateMany`, whose payload is scalar-only (a Prisma constraint), so nested writes are not available on update — do the update and the relation change as separate operations, or in an explicit endpoint.
 
 Example — create a project with a new task and connect existing tags:
@@ -140,6 +142,22 @@ POST /projects
 
 **Keep `forbidNonWhitelisted: true` on** so a disallowed operator (e.g. `set`) **fails loud** with a `400`. Never run `whitelist` in strip-only mode on writes — it would silently drop the payload.
 
+### Nesting depth: one level over HTTP CRUD
+
+The generated nested-write DTOs go **one level deep**. A nested `create` DTO contains the related model's **scalar fields only** (plus its `connect`) — it does **not** expose that model's *own* relations. This is deliberate: it keeps the generated DTOs free of circular references.
+
+Consequence for CRUD requests:
+
+- **One level works:** `project.create` with `tasks: { create: [...] }` or `tags: { connect: [...] }`. ✅
+- **Two+ levels are rejected with `400`:** e.g. `project.create` → `tasks: { create: [{ title, comments: { create: [...] } }] }`. The inner `comments` key is not on the (scalar-only) task nested-create DTO, so `forbidNonWhitelisted` rejects it. This fails **loud**, never silently.
+
+Note the two layers behave differently on purpose:
+
+- **The proxy enforcement is fully recursive** — it authorizes nested `create`/`connect` at *any* depth (each level checked against that model's `create` / `connect` rule). So deep nesting is safe wherever it can reach the proxy.
+- **The generated DTOs cap the HTTP surface at one level.** Deep nesting simply isn't expressible through generic CRUD.
+
+**To do multi-level nested writes, use an explicit controller/service method** that calls `prismaService.model.<x>.create(...)` with the deep payload — the proxy still enforces the `create`/`connect` allowlist recursively there. Do not try to widen the generated DTOs to accept deeper nesting.
+
 ---
 
 ## After changing the schema

package/docs/limitations.md

@@ -38,6 +38,10 @@ Let the generated resolvers serve the data (they go through `PrismaService`); a
 
 You can `select: { _count: ... }`, but ABAC conditions are **not** applied inside a `_count` sub-selection. Don't rely on `_count` to reflect only rows the caller may see.
 
+### Nested writes over HTTP CRUD are one level deep
+
+Generated CRUD accepts nested `create`/`connect` **one level deep only** — a `project.create` may nest tasks/tags, but not a task that itself nests comments (the second level `400`s under `forbidNonWhitelisted`). The proxy's authorization is recursive; the *DTO* surface is the cap, kept one level to avoid circular DTOs. For multi-level nested writes use an explicit endpoint that calls `prismaService.model.*.create(...)`. See [dtos.md](./dtos.md#nesting-depth-one-level-over-http-crud).
+
 ---
 
 ## Sharp edges to know about
@@ -47,6 +51,8 @@ You can `select: { _count: ... }`, but ABAC conditions are **not** applied insid
 - **Role strings are not type-checked.** `PermissionsConfig` keys are plain strings; a typo (`ADIMN`) silently yields "no permissions" → default-deny for that role. Double-check role spelling against your `Role` enum.
 - **No audit logging of denials.** A refused request returns `403` but emits no structured audit event; per-request diagnostics are opt-in via `prismaService.debugQueries(true)`.
 - **Exposed models are a full bypass.** `@ExposeModels` / `@Permission(a, [models])` / `withExposedModels` disable row *and* field filtering for the listed models within that scope. Keep the scope as narrow as possible.
+- **`connect` is one rule per target model, not per relation.** Every foreign key that points at model `T` — from any relation, on any creating model — is authorized by the single `T.connect` rule for the role. You can't say "attach a project as a task's parent (members OK)" but "attach a project for a membership (owner only)" with different `connect` conditions; both use `Project.connect`. Make the rule the union of what any referencing relation needs, and enforce finer distinctions in an explicit endpoint.
+- **The config is validated at boot; a bad config stops the app.** A create condition that references a relation, or a required foreign key whose target lacks a `connect` rule for a role that can create, is a startup error (not a runtime one). This is deliberate — the alternative is a silent runtime `403`. The error message names exactly what to fix.
 
 ---
 

package/docs/permissions.md

@@ -59,20 +59,31 @@ Shape: `PermissionsConfig[Model][Role][action]`, where each `action` value is ei
 
 > `aggregate` is **not** a supported permission action yet — see [limitations.md](./limitations.md).
 
-### The `connect` action
+### The `connect` action — authorizes every relationship a create establishes
 
-When a `create` payload nests `{ relation: { connect: {...} } }` (linking an existing record), the framework checks the **target model's `connect` rule** — a **dedicated** action, separate from reads. This exists because *being able to see a record is not permission to associate it* (seeing a team ≠ being allowed to join it).
+A `create` condition judges the created model's **own scalar fields only** — it never reaches across a relation. All relationship authorization lives in the `connect` action. Whenever a `create` payload establishes a link to model `T`, the framework checks **`T`'s `connect` rule**, a **dedicated** action separate from reads (*being able to see a record is not permission to associate it* — seeing a team ≠ being allowed to join it). This applies however the link is supplied:
+
+| Payload | Authorized by |
+|---|---|
+| a raw scalar foreign key (`teamId: 7`) | `Team.connect` |
+| `team: { connect: { id: 7 } }` | `Team.connect` |
+| `team: { create: {...} }` (nested create) | `Team.create`, recursively |
+| the back-FK to the row you're nested under | trusted — not re-checked |
 
 ```ts
 Team: {
   USER: {
-    findMany: { conditions: { ... } },        // who can SEE a team
-    connect:  { conditions: { ownerId: $UID } } // who can ATTACH a team to something they're creating
+    findMany: { conditions: { ... } },          // who can SEE a team
+    connect:  { conditions: { ownerId: $UID } }, // who can ATTACH a team to a row they're creating
   },
 }
 ```
 
-The `connect` rule's conditions are evaluated against the candidate record. **Default-deny, no fallback:** if the target model has no `connect` rule, the connect is refused. See [dtos.md](./dtos.md#relations--nested-writes) for the nested-write allowlist (`create` / `connect` only).
+The `connect` rule's conditions are evaluated against the candidate record. **Default-deny, no fallback:** if the target model has no `connect` rule, the association is refused — a raw FK cannot bypass it. The one exception is the foreign key Prisma fills in automatically for a child created *inside* its parent's payload: that back-reference is trusted, because the parent authorized itself.
+
+> **Boot validation.** Because a raw FK now needs a `connect` rule, the framework validates the config against the schema **at startup**. If a model a role can `create` has a **required** foreign key whose target lacks a `connect` rule for that role, the app **refuses to boot** (it would always `403`). An **optional** FK in the same situation logs a warning. A `create` condition that references a relation is also a boot error. Fix the config or the app won't start. See [dtos.md](./dtos.md#relations--nested-writes) for the nested-write allowlist (`create` / `connect` only).
+
+> **One `connect` rule per target model.** `connect` is keyed on `[model][role]`, so it can't vary by *which* relation references the model — e.g. "attach a project as a task's parent" and "attach a project for a membership" share one `Project.connect` rule. Make it the union of what any referencing relation needs, and enforce anything finer in an explicit endpoint.
 
 ### Action fallback chains
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@appxdigital/appx-core",
-    "version": "0.1.121-beta.10",
+    "version": "0.1.121-beta.12",
     "description": "Appx Core is a library that provides a set of tools to help you build your application faster.",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",