@appxdigital/appx-core 0.1.121-beta.8 → 0.1.121

package/CHANGELOG.md

@@ -18,6 +18,17 @@ This project follows the `MAJOR.MINOR.PATCH` scheme in `package.json`.
 
 Hardening release: request validation, boot configuration, generated-CRUD DTOs, and data-access create enforcement.
 
+> ## ⚠️ REQUIRED migration — upgrading the dependency is NOT enough
+>
+> **This is a security release, and its protections are INERT until you adapt your codebase.** Bumping `@appxdigital/appx-core` to `0.1.121` (including any `0.1.121-beta.x`) and doing nothing else leaves your app **vulnerable** — generated `POST`/`PUT` endpoints keep accepting arbitrary fields (mass-assignment), because the request-validation DTOs only take effect once you regenerate them **and** wire them into your controllers.
+>
+> **You MUST complete every step in [Migration](#migration) below — this is not optional and must not be skipped.** In particular:
+> - **Step 4 (generated-CRUD DTOs) is mandatory**: run `npx appx generate`, then add the DTO-typed `create`/`update` overrides to *every* existing generated controller. Generation alone does nothing; the controllers must import and use the DTOs.
+> - Steps 1–3 (`main.ts` / `app.module.ts`) are required for the boot-time hardening (validation pipe, session secret, CORS, `NODE_ENV`) to apply.
+> - Step 5 is a behaviour change (create is now permission-checked) — review it before deploying.
+>
+> **For AI agents:** do not report this upgrade as complete until steps 1–5 are applied and the app builds. If you only changed the version number, the task is unfinished.
+
 ### Added
 
 - **`setupCoreSecurity(app, options?)`** — one call that applies baseline HTTP hardening: a global `ValidationPipe` (`{ transform: true, whitelist: true, forbidNonWhitelisted: true }`), CORS (`cors` option, default `{ origin: 'http://localhost:3000', credentials: true }`, throws if `origin: '*'` is combined with `credentials: true`), and **Helmet** security headers (on by default; `helmet` option to tune/disable). `helmet` is a new peer dependency.
@@ -40,10 +51,11 @@ A scalar field is included unless it is: the primary key (`@id`), a server-manag
 - `app.module.ts` uses `coreEnvFilePath()` for `envFilePath`.
 - Generated `package.json` adds `helmet`; the `start` script sets `NODE_ENV=development`.
 - `AuthController.getAllSessions` / `closeSpecificSession` use `@UseGuards(AuthenticatedGuard)`.
+- `app.module.ts` imports `AuthModule.forRoot()` (not the bare `AuthModule`) — see the migration note below.
 
 ### Migration
 
-> For existing projects. All edits are to files you own (`main.ts` / `app.module.ts` / `package.json` / your generated controllers). Safe to hand to an AI coding agent.
+> **Required for every existing project. All five steps must be applied** — the edits are to files you own (`main.ts` / `app.module.ts` / `package.json` / your generated controllers), so they are safe to hand to an AI coding agent, but they are **not optional**. The app is not secured until they are done and it builds.
 
 **1. Request validation & HTTP hardening — `src/main.ts`.**
 ```ts
@@ -78,12 +90,16 @@ import { coreEnvFilePath } from '@appxdigital/appx-core';
 ```
 Set `NODE_ENV` explicitly (`production` / `development`) in every deploy and start script — boot fails if it is unset. If you use a bare `nest start`, change it to `cross-env NODE_ENV=development nest start`. (`coreEnvFilePath()` loads `.env.<NODE_ENV>` with `.env` as a fallback, so a plain `.env` still works.)
 
-**4. Generated-CRUD DTOs.**
+**4. Generated-CRUD DTOs — MANDATORY (this is the mass-assignment fix; do not skip).**
+
+Without this step, your generated `POST`/`PUT` endpoints still accept arbitrary fields — the vulnerability this release closes stays open. Two parts, **both required**:
+
+(a) Regenerate:
 ```bash
 npm install @appxdigital/appx-core@^0.1.121
 npx appx generate
 ```
-Then **add the DTO-typed overrides to each existing generated controller** (generated once, not overwritten):
+(b) **Add the DTO-typed overrides to EVERY existing generated controller** (they are generated once and never overwritten, so `appx generate` will NOT add them for you — you must edit each controller by hand or delete and regenerate it):
 ```ts
 import { Body, Param, Post, Put } from '@nestjs/common';
 import { Permission } from '@appxdigital/appx-core';
@@ -96,7 +112,37 @@ async create(@Body() data: Create<Model>Dto) { return super.create(data as any);
 @Put(':id') @Permission('updateMany')
 async update(@Param('id') id: string, @Body() data: Update<Model>Dto) { return super.update(id, data as any); }
 ```
-(Or delete an un-customized controller and re-run `appx generate` for the new template.) Add custom validation in the hand-owned `dto/*.dto.ts` subclasses — never in the `.generated.dto.ts` base. Lock sensitive columns with `/// @NoWrite` (all roles) or `restrictedFields` on the permission (per role), then regenerate.
+(Or delete an un-customized controller and re-run `appx generate` for the new template.) Add custom validation in the hand-owned `dto/*.dto.ts` subclasses — never in the `.generated.dto.ts` base. Lock sensitive columns with `/// @NoWrite` (all roles) or `restrictedFields` on the permission (per role), then regenerate. To drop a field from one endpoint's DTO, extend `OmitType(<Model>GeneratedDto, ['field'] as const)`. Full details in [`docs/dtos.md`](../docs/dtos.md).
+
+> **Nested relation writes are now an explicit, permission-gated allowlist — this is a behaviour restriction; a migrating agent MUST flag it to the developer.** Generated **create** DTOs accept only two nested operators, each authorized by ABAC: **`create`** (checked against the related model's `create` rule) and **`connect`** (checked against the related model's new dedicated **`connect`** permission — a `connect` rule is required; no rule ⇒ refused). Every other operator (`set`, `disconnect`, `update`, `upsert`, `delete`, …) is rejected (`400`). Nested writes are available on **`create` only** — `update` resolves to `updateMany`, whose payload is scalar-only. **Keep `forbidNonWhitelisted: true` on (fail loud); never `whitelist`-strip on writes.**
+>
+> **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 write establishes is now authorized by the target model's `connect` rule** — on a `create` (nested `connect`, nested `create`, **or a plain scalar FK** like `ownerId: 7`) **and on an `update` that re-points a foreign key** (`{ teacherId: 5 }` / `{ teacherId: { set: 5 } }`). 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 **or update** can set a foreign key whose target has **no `connect` rule** for that role, **the app refuses to start** (setting it would `403`). A required-on-create FK reports as such; a `@NoWrite`/`@Role(none)` FK column is exempt (it can't be written); a `create` condition that references a relation, or a relation-scoped `connect` on a non-writable field, are also boot errors.
+>
+> **`restrictedFields` removed.** The per-role body-strip option on a permission action (`restrictedFields: ['x']`) is gone. Migrate: mark a never-client-writable column `/// @NoWrite` (or `/// @Role(none)`); drop a field from one endpoint with `OmitType`; force an owner id with `setUserIdField`; and for a genuinely per-role write difference, use a dedicated endpoint (generic CRUD can't vary a field by role). See [`docs/dtos.md`](../docs/dtos.md#per-role-differences).
+>
+> **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. If a *specific* relation needs its own (stricter) rule — "a class's teacher must be a teacher" — declare it on the source instead: `Source[Role].relations.<field>.connect`. That also satisfies the requirement, so the target model then needs no `connect` rule for that reference.
+> 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).
+
+**6. Auth module — `AuthModule` → `AuthModule.forRoot()` (`src/app.module.ts`).**
+The bare `AuthModule` no longer registers anything; wire it as `AuthModule.forRoot()`
+(all providers + the built-in `/auth` controller). This exists so the controller
+can be conditionally omitted: to override the auth endpoints (e.g. widen
+registration to accept `name`), import `AuthModule.forRoot({ controller: false })`
+and register your own controller that `extends AuthController` at the same `/auth`
+prefix. The auth building blocks (`AuthController`, `AuthService`, `RegisterDto`,
+`UserDto`, the Passport strategies, guards) are now exported from the package root
+— stop importing them from `@appxdigital/appx-core/dist/...`. Full guide:
+[`docs/authentication.md`](../docs/authentication.md).
 
 **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.

package/PRERELEASES.md

@@ -1,5 +1,13 @@
 # Prerelease log
 
+> ## ⚠️ Every `0.1.121-beta.x` is part of a SECURITY-hardening release — a required migration applies
+>
+> Adopting any `0.1.121` beta from `0.1.120` (or earlier) requires the **mandatory migration in [`CHANGELOG.md`](./CHANGELOG.md) under `[0.1.121]`** — most importantly **regenerating the per-model DTOs and wiring them into your controllers** (`npx appx generate` + adding the DTO-typed `create`/`update` overrides to every generated controller). **Bumping the version without doing this leaves generated `POST`/`PUT` endpoints accepting arbitrary fields.**
+>
+> The per-build notes below are **incremental deltas relative to the previous beta**. When an entry says "no code change" or "regenerate not required", it means *nothing new to do versus the prior beta* — it does **not** waive the `[0.1.121]` migration you owe when coming from `0.1.120`.
+>
+> **AI agents:** do not report a `0.1.121` upgrade as done until the `CHANGELOG.md [0.1.121]` migration steps 1–5 are applied and the project builds.
+
 Granular notes for **alpha / beta** builds of both packages —
 `@appxdigital/appx-core` (library) and `@appxdigital/appx-core-cli` (CLI) —
 newest first. Entries are labelled by package. These are the builds you install
@@ -23,6 +31,127 @@ Prereleases are excluded from normal semver range resolution, so a project on
 
 ---
 
+## [0.1.121-beta.16] — unreleased
+
+**Fix — `AuthModule.forRoot({ controller: false })` now actually omits the
+controller.** In beta.15 the controller was also declared on the static `@Module()`,
+and NestJS *extends* (does not replace) that metadata with `forRoot()`'s — so
+`AuthController` stayed registered and overriding `/auth/register` produced a
+duplicate route (the base `RegisterDto` won → extra fields like `name` were
+rejected). All wiring now lives in `forRoot()`.
+
+- **Migration:** import **`AuthModule.forRoot()`**, not the bare `AuthModule` (which
+  now registers nothing). The scaffold is updated. `forRoot({ controller: false })`
+  omits the built-in controller so your own can take over `/auth`. Regression
+  test added (`test/unit/auth-module.spec.ts`).
+
+## [0.1.121-beta.15] — unreleased
+
+**Library / docs. Additive — no behaviour change.** Auth is now extensible from
+the package root instead of deep `dist/` imports.
+
+- **Exported the auth building blocks** from `@appxdigital/appx-core`:
+  `AuthController`, `AuthService`, `RegisterDto`, `UserDto`, `AuthField`,
+  `LocalStrategy`, `JwtStrategy`, `RefreshTokenStrategy`, `LocalAuthGuard`,
+  `RefreshTokenGuard`, `SessionSerializer`, `SessionAuthGuard`. Stop importing
+  these from `@appxdigital/appx-core/dist/...` — deep paths are internal.
+- **`AuthModule.forRoot({ controller?: boolean })`** — importing
+  `AuthModule.forRoot({ controller: false })` registers every auth provider
+  globally but **not** the built-in `AuthController`, so you can register your own
+  controller (e.g. `extends AuthController`) at the same `/auth` prefix with no
+  duplicate route. Importing the plain `AuthModule` is unchanged (still registers
+  the controller).
+- **New doc `docs/authentication.md`** — the built-in `/auth` surface and how to
+  override framework internals (widen `RegisterDto` to accept e.g. `name`, extend
+  `AuthService`, swap a Passport strategy), wired at the same prefix in `AppModule`.
+
+## [0.1.121-beta.14] — unreleased
+
+**Library / types.** `RolePermissions.relations` is now usable in a properly
+typed `PermissionsConfigType` (no `as any`) — the catch-all index signature no
+longer collides with the `relations` key. Guarded by a type-contract test. The
+boot validator now takes `PermissionsConfigType` directly. No runtime change.
+
+## [0.1.121-beta.13] — unreleased
+
+**Library.** **Relation-scoped `connect` rules.** A `connect` rule can now be
+declared on the **source** model, keyed by the relation field
+(`relations: { teacher: { connect: { conditions: {...} } } }`), to constrain who
+may be attached *through that relation* — something the per-target-model
+`connect` rule can't express (e.g. "a class's teacher must be a teacher"). When
+both the relation rule and the target's `connect` rule exist they are **ANDed**
+(the relation rule only strengthens); when only the relation rule exists it
+stands alone, so the target model needs no `connect` rule. The boot validator
+accepts either placement. Additive and backward-compatible — no `relations` block
+means unchanged behaviour. See `docs/permissions.md`.
+
+**Connect authorization now also covers `update`.** Re-pointing a foreign key on
+an `update` (`{ teacherId: 5 }` or `{ teacherId: { set: 5 } }`) is authorized by
+the same `connect` rules as `create` — previously the update path set foreign
+keys with no connect check. The `relations` config is shared across create and
+update.
+
+**Boot validator is now strict about all settable FKs.** Any foreign key a role
+can set on create **or** update whose target lacks a `connect` rule is a boot
+**error** (previously optional/update FKs were warnings). `@NoWrite` / `@Role(none)`
+columns are exempt (never client-writable), and a relation-scoped `connect` on a
+non-writable field is flagged as a contradiction.
+
+**`restrictedFields` removed (breaking).** The per-role body-strip option on a
+permission action is gone; the `CoreController` no longer strips fields. Migrate
+to `/// @NoWrite` / `OmitType` / `setUserIdField` / a dedicated endpoint — see the
+`[0.1.121]` migration in `CHANGELOG.md` and `docs/dtos.md`.
+
+## [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,
+permission-gated allowlist.** A `create` body may nest **`create`** and
+**`connect`** on its relations; both are authorized by ABAC (`create` → the
+related model's `create` rule, recursively; `connect` → the related model's new
+dedicated **`connect`** permission — a `connect` rule is required, because being
+able to *read* a record does not authorize associating it). Every other nested
+operator (`set` / `disconnect` / `update` / `upsert` / `delete` / …) is rejected
+at both the DTO layer (not emitted → `400`) and the proxy (throws). Nested
+writes are available on **`create` only** (`update` resolves to `updateMany`,
+which is scalar-only).
+
+- **Behaviour restriction — review on upgrade.** If a project used other nested
+  operators through CRUD, or connected models without a `connect` rule, those
+  requests now fail. Add `connect` rules where needed; move unsupported nested
+  writes to explicit endpoints. Keep `forbidNonWhitelisted: true` (fail loud).
+
+## [0.1.121-beta.9] — unreleased
+
+**Docs / packaging.** No code change.
+
+- Added a **`docs/` folder** (now shipped inside the npm package) — the
+  framework's source-of-truth guide: `permissions.md` (RBAC config +
+  `@Permission`/`@ExposeModels`), `data-access.md` (the Prisma proxy, ABAC
+  enforcement, single-record method contract, relations, transactions) and
+  `limitations.md` (not-ready features incl. `aggregate`/GraphQL, and caveats).
+- **Clarified the `[0.1.121]` migration in `CHANGELOG.md`.** It is now explicit
+  that regenerating the per-model DTOs and wiring them into every controller is
+  **mandatory** (it is the mass-assignment fix), and that a version bump without
+  it leaves `POST`/`PUT` endpoints accepting arbitrary fields.
+
 ## [0.1.121-beta.8] — unreleased
 
 **Library.**

package/dist/common/config/permissionsConfigTypes.d.ts

@@ -48,15 +48,31 @@ export type FieldConditions<M extends ModelKey<RuntimeClient>, A extends Methods
 export interface ActionPermission<M extends ModelKey<RuntimeClient> = ModelKey<RuntimeClient>, A extends MethodsWithWhere<RuntimeClient, M> = MethodsWithWhere<RuntimeClient, M>> {
     conditions: FieldConditions<M, A> | FieldConditions<M, A>[];
     setUserIdField?: string;
-    restrictedFields?: string[];
 }
+/**
+ * A relation-scoped `connect` rule, declared on the SOURCE model and keyed by
+ * the relation field. It authorizes attaching a target through *that specific
+ * relation* (e.g. who may be a class's `teacher`). When the target model also
+ * declares a `connect` rule, the two are ANDed (the relation rule can only
+ * strengthen, never weaken, the target's rule). When only the relation rule
+ * exists, it stands alone — the target model then needs no `connect` rule.
+ */
+export interface RelationConnectRule {
+    connect: 'ALL' | {
+        conditions?: unknown | unknown[];
+    };
+}
+export type RelationConnectMap = {
+    [relationField: string]: RelationConnectRule;
+};
 export type RolePermissions<M extends ModelKey<RuntimeClient> = ModelKey<RuntimeClient>> = {
     [A in MethodsWithWhere<RuntimeClient, M>]?: 'ALL' | ActionPermission<M, A>;
 } & {
-    [custom: string]: 'ALL' | {
+    relations?: RelationConnectMap;
+} & {
+    [custom: string]: 'ALL' | RelationConnectMap | {
         conditions?: unknown | unknown[];
         setUserIdField?: string;
-        restrictedFields?: string[];
     };
 };
 export type ModelPermissions<M extends ModelKey<RuntimeClient> = ModelKey<RuntimeClient>> = {

package/dist/common/config/permissionsConfigTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissionsConfigTypes.d.ts","sourceRoot":"","sources":["../../../src/common/config/permissionsConfigTypes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"permissionsConfigTypes.d.ts","sourceRoot":"","sources":["../../../src/common/config/permissionsConfigTypes.ts"],"names":[],"mappings":"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"}

package/dist/config/generate-dtos.js

@@ -45,7 +45,14 @@ const utils_1 = require("./utils");
  *   - a server-managed timestamp (`@default(now())` or `@updatedAt`),
  *   - annotated `/// @NoWrite`, or
  *   - annotated `/// @Role(none)` (readable by nobody ⇒ not CRUD-writable).
- * Relation navigation fields are excluded; their scalar foreign keys are kept.
+ *
+ * Nested relation writes (CREATE DTOs only — `updateMany` takes scalar data):
+ *   Each relation gets a nested-write member exposing ONLY the operators the
+ *   data-access proxy authorizes: `create` (validated against the related
+ *   model's writable scalars) and `connect` (validated against the related
+ *   model's unique fields). Other operators (`set`/`disconnect`/`update`/…) are
+ *   deliberately NOT emitted, so the whitelist pipe rejects them. The proxy
+ *   enforces the matching ABAC rule for each (`create` rule / `connect` rule).
  */
 const cwd = process.cwd();
 // Read the consumer's generated Prisma client for the DMMF (authoritative
@@ -54,6 +61,9 @@ const cwd = process.cwd();
 const { Prisma } = require(path.join(cwd, 'node_modules', '@prisma/client'));
 const generatedDtoRoot = path.join(cwd, 'src/generated/dto');
 const modulesRoot = path.join(cwd, 'src/modules');
+const modelsByName = {};
+for (const m of Prisma.dmmf.datamodel.models)
+    modelsByName[m.name] = m;
 function isNoWrite(doc) {
     if (!doc)
         return false;
@@ -98,7 +108,7 @@ function mapField(field) {
             return { validator: 'Allow', tsType: 'any' };
     }
 }
-function writableFields(model) {
+function writableFields(model, omit = []) {
     return model.fields.filter((f) => {
         if (f.kind === 'object')
             return false; // relation navigation
@@ -108,25 +118,32 @@ function writableFields(model) {
             return false;
         if (isNoWrite(f.documentation))
             return false;
+        if (omit.includes(f.name))
+            return false;
         return true;
     });
 }
-/** Renders a base DTO class body + its import block. */
-function renderBaseDto(className, fields, mode) {
-    const validatorImports = new Set();
-    const enumImports = new Set();
+/** id + unique scalar fields (for a connect-by DTO). */
+function connectFields(model) {
+    return model.fields.filter((f) => f.kind !== 'object' && (f.isId || f.isUnique));
+}
+/** The scalar FK column(s) the parent sets automatically — omit from a nested create. */
+function backFkColumns(relatedModel, relationName) {
+    const inverse = relatedModel.fields.find((f) => f.kind === 'object' && f.relationName === relationName && (f.relationFromFields || []).length > 0);
+    return inverse ? inverse.relationFromFields || [] : [];
+}
+/** Renders class-body lines for a set of scalar/enum fields; collects imports. */
+function renderScalarLines(fields, mode, validatorImports, enumImports) {
     const lines = [];
     for (const field of fields) {
         const m = mapField(field);
         validatorImports.add(m.validator);
         if (m.enumArg)
             enumImports.add(m.enumArg);
-        // update: everything optional. create: optional if not required or has a default.
-        const optional = mode === 'update' || !field.isRequired || field.hasDefaultValue;
+        // update / connect: everything optional. create: optional if not required or defaulted.
+        const optional = mode !== 'create' || !field.isRequired || field.hasDefaultValue;
         const isList = field.isList;
         const tsType = isList ? `${m.tsType}[]` : m.tsType;
-        // Compose the validator decorator. @Allow takes no options; for other
-        // validators on a list field, add `{ each: true }` (+ @IsArray).
         let validatorDecorator;
         if (m.validator === 'Allow') {
             validatorDecorator = '@Allow()';
@@ -153,19 +170,89 @@ function renderBaseDto(className, fields, mode) {
         lines.push(`    ${field.name}${optional ? '?' : '!'}: ${tsType};`);
         lines.push('');
     }
+    return lines;
+}
+function renderClass(className, bodyLines) {
+    return `export class ${className} {\n` + (bodyLines.length ? bodyLines.join('\n') : '') + `}\n`;
+}
+/**
+ * For a model's CREATE DTO, render the nested-write classes for each relation
+ * plus the property lines to add to the parent class. Nested create classes are
+ * scalars-only (no deeper relations) so there are no circular imports.
+ */
+function renderRelationNestedWrites(model, validatorImports, enumImports, transformerImports) {
+    const classes = [];
+    const parentLines = [];
+    const relations = model.fields.filter((f) => f.kind === 'object');
+    for (const rel of relations) {
+        const related = modelsByName[rel.type];
+        if (!related)
+            continue;
+        const relCap = rel.name.charAt(0).toUpperCase() + rel.name.slice(1);
+        const createCls = `${model.name}${relCap}CreateNestedDto`;
+        const connectCls = `${model.name}${relCap}ConnectNestedDto`;
+        const writeCls = `${model.name}${relCap}NestedWriteDto`;
+        // create: related writable scalars minus the back-reference FK.
+        const omit = backFkColumns(related, rel.relationName);
+        classes.push(renderClass(createCls, renderScalarLines(writableFields(related, omit), 'create', validatorImports, enumImports)));
+        // connect: related unique fields (all optional).
+        const conn = connectFields(related);
+        classes.push(renderClass(connectCls, renderScalarLines(conn, 'connect', validatorImports, enumImports)));
+        // nested-write: create? / connect? only.
+        transformerImports.add('Type');
+        validatorImports.add('IsOptional');
+        validatorImports.add('ValidateNested');
+        const eachArg = rel.isList ? '{ each: true }' : '';
+        const arrSuffix = rel.isList ? '[]' : '';
+        if (rel.isList)
+            validatorImports.add('IsArray');
+        const opLines = [];
+        for (const [op, cls] of [['create', createCls], ['connect', connectCls]]) {
+            if (rel.isList)
+                opLines.push('    @IsArray()');
+            opLines.push('    @IsOptional()');
+            opLines.push(`    @ValidateNested(${eachArg})`);
+            opLines.push(`    @Type(() => ${cls})`);
+            opLines.push(`    ${op}?: ${cls}${arrSuffix};`);
+            opLines.push('');
+        }
+        classes.push(renderClass(writeCls, opLines));
+        // property on the parent CREATE DTO.
+        parentLines.push('    @IsOptional()');
+        parentLines.push('    @ValidateNested()');
+        parentLines.push(`    @Type(() => ${writeCls})`);
+        parentLines.push(`    ${rel.name}?: ${writeCls};`);
+        parentLines.push('');
+    }
+    return { classes, parentLines };
+}
+/** Renders a base DTO file (nested relation writes on create only). */
+function renderBaseDto(className, model, mode) {
+    const validatorImports = new Set();
+    const enumImports = new Set();
+    const transformerImports = new Set();
+    const scalarLines = renderScalarLines(writableFields(model), mode, validatorImports, enumImports);
+    let nested = { classes: [], parentLines: [] };
+    if (mode === 'create') {
+        nested = renderRelationNestedWrites(model, validatorImports, enumImports, transformerImports);
+    }
+    const parentClass = renderClass(className, [...scalarLines, ...nested.parentLines]);
     const importLines = [];
     if (validatorImports.size > 0) {
         importLines.push(`import { ${[...validatorImports].sort().join(', ')} } from 'class-validator';`);
     }
+    if (transformerImports.size > 0) {
+        importLines.push(`import { ${[...transformerImports].sort().join(', ')} } from 'class-transformer';`);
+    }
     if (enumImports.size > 0) {
         importLines.push(`import { ${[...enumImports].sort().join(', ')} } from '@prisma/client';`);
     }
     return (utils_1.GENERATED_BANNER +
         '\n' +
         (importLines.length ? importLines.join('\n') + '\n\n' : '') +
-        `export class ${className} {\n` +
-        (lines.length ? lines.map((l) => l).join('\n') : '') +
-        `}\n`);
+        // nested classes first (referenced by @Type in the parent).
+        (nested.classes.length ? nested.classes.join('\n') + '\n' : '') +
+        parentClass);
 }
 /** Renders the hand-owned subclass (generated once, then customizable). */
 function renderSubclassDto(subclass, baseClass, importPath) {
@@ -182,14 +269,13 @@ for (const model of Prisma.dmmf.datamodel.models) {
     const folder = (0, utils_1.pascalToKebabCase)(modelName); // kebab, e.g. project-member
     if (utils_1.IGNORE_FOLDERS.includes(folder))
         continue;
-    const fields = writableFields(model);
     for (const mode of ['create', 'update']) {
         const capMode = mode.charAt(0).toUpperCase() + mode.slice(1);
         const baseClass = `${capMode}${modelName}GeneratedDto`;
         const subclass = `${capMode}${modelName}Dto`;
         // Base (overwritten, gitignored).
         const basePath = path.join(generatedDtoRoot, folder, `${mode}-${folder}.generated.dto.ts`);
-        (0, utils_1.writeGeneratedFile)(basePath, renderBaseDto(baseClass, fields, mode));
+        (0, utils_1.writeGeneratedFile)(basePath, renderBaseDto(baseClass, model, mode));
         // Subclass (once, hand-owned, committed).
         const subPath = path.join(modulesRoot, folder, 'dto', `${mode}-${folder}.dto.ts`);
         const importPath = `../../../generated/dto/${folder}/${mode}-${folder}.generated.dto`;

package/dist/index.d.ts

@@ -6,6 +6,18 @@ export * from './graphql/graphql.module';
 export * from './graphql/generic.resolver';
 export * from './tasks/session-cleanup.service';
 export * from './modules/auth/auth.module';
+export * from './modules/auth/auth.controller';
+export * from './modules/auth/auth.service';
+export * from './modules/auth/dto/register.dto';
+export * from './modules/auth/dto/user.dto';
+export * from './modules/auth/auth-field.decorator';
+export * from './modules/auth/local.strategy';
+export * from './modules/auth/local-auth.guard';
+export * from './modules/auth/jwt.strategy';
+export * from './modules/auth/refresh-token.strategy';
+export * from './modules/auth/refresh-token.guard';
+export * from './modules/auth/session/session-serializer';
+export * from './modules/auth/session/session-auth.guard';
 export * from './modules/auth/session/session-store';
 export * from './common/guards/rbac.guard';
 export * from './common/guards/user-population.guard';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sCAAsC,CAAC;AACrD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uCAAuC,CAAC;AACtD,cAAc,yBAAyB,CAAC;AACxC,cAAc,0CAA0C,CAAC;AACzD,cAAc,wCAAwC,CAAC;AACvD,cAAc,iCAAiC,CAAC;AAChD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,oBAAoB,CAAC;AACnC,cAAc,mCAAmC,CAAC;AAClD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,wCAAwC,CAAC;AACvD,cAAc,+CAA+C,CAAC;AAC9D,cAAc,uCAAuC,CAAC;AACtD,cAAc,oCAAoC,CAAC;AACnD,cAAc,0CAA0C,CAAC;AACzD,cAAc,oCAAoC,CAAC;AACnD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,oCAAoC,CAAC;AACnD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAI3C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qCAAqC,CAAC;AACpD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uCAAuC,CAAC;AACtD,cAAc,oCAAoC,CAAC;AACnD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,sCAAsC,CAAC;AACrD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uCAAuC,CAAC;AACtD,cAAc,yBAAyB,CAAC;AACxC,cAAc,0CAA0C,CAAC;AACzD,cAAc,wCAAwC,CAAC;AACvD,cAAc,iCAAiC,CAAC;AAChD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,oBAAoB,CAAC;AACnC,cAAc,mCAAmC,CAAC;AAClD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,wCAAwC,CAAC;AACvD,cAAc,+CAA+C,CAAC;AAC9D,cAAc,uCAAuC,CAAC;AACtD,cAAc,oCAAoC,CAAC;AACnD,cAAc,0CAA0C,CAAC;AACzD,cAAc,oCAAoC,CAAC;AACnD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,oCAAoC,CAAC;AACnD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC"}

package/dist/index.js

@@ -22,6 +22,21 @@ __exportStar(require("./graphql/graphql.module"), exports);
 __exportStar(require("./graphql/generic.resolver"), exports);
 __exportStar(require("./tasks/session-cleanup.service"), exports);
 __exportStar(require("./modules/auth/auth.module"), exports);
+// Auth building blocks — exported so consumers can extend/override them
+// (custom AuthController, widened RegisterDto, custom Passport strategy) without
+// deep-importing from `dist/`. See docs/authentication.md.
+__exportStar(require("./modules/auth/auth.controller"), exports);
+__exportStar(require("./modules/auth/auth.service"), exports);
+__exportStar(require("./modules/auth/dto/register.dto"), exports);
+__exportStar(require("./modules/auth/dto/user.dto"), exports);
+__exportStar(require("./modules/auth/auth-field.decorator"), exports);
+__exportStar(require("./modules/auth/local.strategy"), exports);
+__exportStar(require("./modules/auth/local-auth.guard"), exports);
+__exportStar(require("./modules/auth/jwt.strategy"), exports);
+__exportStar(require("./modules/auth/refresh-token.strategy"), exports);
+__exportStar(require("./modules/auth/refresh-token.guard"), exports);
+__exportStar(require("./modules/auth/session/session-serializer"), exports);
+__exportStar(require("./modules/auth/session/session-auth.guard"), exports);
 __exportStar(require("./modules/auth/session/session-store"), exports);
 __exportStar(require("./common/guards/rbac.guard"), exports);
 __exportStar(require("./common/guards/user-population.guard"), exports);

package/dist/modules/auth/auth.module.d.ts

@@ -1,3 +1,19 @@
+import { DynamicModule } from '@nestjs/common';
 export declare class AuthModule {
+    /**
+     * Wires the auth module. **Always use `AuthModule.forRoot()`** — importing the
+     * bare `AuthModule` registers nothing (all wiring is here so the controller
+     * can be conditionally omitted).
+     *
+     * `AuthModule.forRoot()` registers the built-in `AuthController` (default).
+     * `AuthModule.forRoot({ controller: false })` registers every auth provider
+     * globally (AuthService, Jwt, Passport, strategies, guards) but NOT the
+     * controller — so you can register your OWN controller (e.g. one that
+     * `extends AuthController`) at the same `/auth` prefix with no duplicate
+     * route. See docs/authentication.md.
+     */
+    static forRoot(options?: {
+        controller?: boolean;
+    }): DynamicModule;
 }
 //# sourceMappingURL=auth.module.d.ts.map

package/dist/modules/auth/auth.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.module.d.ts","sourceRoot":"","sources":["../../../src/modules/auth/auth.module.ts"],"names":[],"mappings":"AAcA,qBAea,UAAU;CACtB"}
+{"version":3,"file":"auth.module.d.ts","sourceRoot":"","sources":["../../../src/modules/auth/auth.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AAkC7D,qBAEa,UAAU;IACnB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE;QAAC,UAAU,CAAC,EAAE,OAAO,CAAA;KAAC,GAAG,aAAa;CAUlE"}

package/dist/modules/auth/auth.module.js

@@ -5,6 +5,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+var AuthModule_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthModule = void 0;
 const common_1 = require("@nestjs/common");
@@ -20,22 +21,50 @@ const jwt_auth_guard_1 = require("./jwt-auth.guard");
 const authenticated_guard_1 = require("./authenticated.guard");
 const jwt_strategy_1 = require("./jwt.strategy");
 const refresh_token_strategy_1 = require("./refresh-token.strategy");
-let AuthModule = exports.AuthModule = class AuthModule {
+// All wiring lives in forRoot() so the controller can be conditionally omitted.
+// The @Module() decorator is intentionally empty: NestJS *extends* (concatenates)
+// the decorator's metadata onto a DynamicModule, so a controller declared there
+// could never be removed by forRoot({ controller: false }).
+const authImports = [
+    config_1.ConfigModule,
+    user_module_1.UserModule,
+    passport_1.PassportModule.register({ session: true }),
+    jwt_1.JwtModule.registerAsync({
+        imports: [config_1.ConfigModule],
+        useFactory: async (config) => ({
+            secret: config.get('JWT_SECRET'),
+            signOptions: { expiresIn: config.get('JWT_EXPIRES_IN', '60m') },
+        }),
+        inject: [config_1.ConfigService],
+    }),
+];
+const authProviders = [auth_service_1.AuthService, local_strategy_1.LocalStrategy, session_serializer_1.SessionSerializer, jwt_strategy_1.JwtStrategy, jwt_auth_guard_1.JwtAuthGuard, authenticated_guard_1.AuthenticatedGuard, refresh_token_strategy_1.RefreshTokenStrategy];
+const authExports = [auth_service_1.AuthService, jwt_auth_guard_1.JwtAuthGuard, authenticated_guard_1.AuthenticatedGuard, jwt_1.JwtModule];
+let AuthModule = exports.AuthModule = AuthModule_1 = class AuthModule {
+    /**
+     * Wires the auth module. **Always use `AuthModule.forRoot()`** — importing the
+     * bare `AuthModule` registers nothing (all wiring is here so the controller
+     * can be conditionally omitted).
+     *
+     * `AuthModule.forRoot()` registers the built-in `AuthController` (default).
+     * `AuthModule.forRoot({ controller: false })` registers every auth provider
+     * globally (AuthService, Jwt, Passport, strategies, guards) but NOT the
+     * controller — so you can register your OWN controller (e.g. one that
+     * `extends AuthController`) at the same `/auth` prefix with no duplicate
+     * route. See docs/authentication.md.
+     */
+    static forRoot(options) {
+        return {
+            module: AuthModule_1,
+            global: true,
+            imports: authImports,
+            providers: authProviders,
+            controllers: options?.controller === false ? [] : [auth_controller_1.AuthController],
+            exports: authExports,
+        };
+    }
 };
-exports.AuthModule = AuthModule = __decorate([
+exports.AuthModule = AuthModule = AuthModule_1 = __decorate([
     (0, common_1.Global)(),
-    (0, common_1.Module)({
-        imports: [config_1.ConfigModule, user_module_1.UserModule, passport_1.PassportModule.register({ session: true }),
-            jwt_1.JwtModule.registerAsync({
-                imports: [config_1.ConfigModule],
-                useFactory: async (config) => ({
-                    secret: config.get('JWT_SECRET'),
-                    signOptions: { expiresIn: config.get('JWT_EXPIRES_IN', '60m') },
-                }),
-                inject: [config_1.ConfigService],
-            }),],
-        providers: [auth_service_1.AuthService, local_strategy_1.LocalStrategy, session_serializer_1.SessionSerializer, jwt_strategy_1.JwtStrategy, jwt_auth_guard_1.JwtAuthGuard, authenticated_guard_1.AuthenticatedGuard, refresh_token_strategy_1.RefreshTokenStrategy],
-        controllers: [auth_controller_1.AuthController],
-        exports: [auth_service_1.AuthService, jwt_auth_guard_1.JwtAuthGuard, authenticated_guard_1.AuthenticatedGuard, jwt_1.JwtModule],
-    })
+    (0, common_1.Module)({})
 ], AuthModule);