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

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,40 @@ 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 || {};
+            const noWrite = this.fieldConfigs[model].noWriteFields || [];
+            relations[model] = Object.keys(relationFields).map((field) => ({
+                field,
+                model: relationFields[field].model,
+                referencingColumn: relationFields[field].referencingColumn,
+                isRequired: relationFields[field].isRequired,
+                kind: relationFields[field].relation,
+                // The scalar FK is client-writable unless the column is @NoWrite / @Role(none).
+                fkWritable: !noWrite.includes(relationFields[field].referencingColumn),
+            }));
+        }
+        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;
     }
@@ -98,9 +131,17 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                                             // 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 relation the write establishes (nested
+                                            // create/connect, or a raw foreign key).
+                                            await this.enforceNestedWrites(String(propKey), params.data, user, userRole);
                                         }
                                         else {
                                             params = this.applyWhereConditions(String(propKey), userRole, params, user, methodKey);
+                                            // An update can re-point a foreign key (scalar column);
+                                            // authorize those changes with the same connect rules as create.
+                                            if (['update', 'updateMany'].includes(methodKey.toString())) {
+                                                await this.enforceNestedWrites(String(propKey), params.data, user, userRole);
+                                            }
                                         }
                                     }
                                     else {
@@ -175,6 +216,7 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
             const fieldTypes = {};
             const scalarFields = [];
             const relationFields = {};
+            const noWriteFields = [];
             for (const field of fields) {
                 let field_name = field.name;
                 const fieldType = field.type;
@@ -184,6 +226,10 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                     if (roleMatch) {
                         fieldConfig[field_name] = roleMatch[1].split(',').map((role) => role.trim());
                     }
+                    // Fields excluded from write DTOs — never client-writable.
+                    if (/@NoWrite\b/.test(commentPart) || /@Role\(\s*none\s*\)/i.test(commentPart)) {
+                        noWriteFields.push(field_name);
+                    }
                 }
                 allFields.push(field_name);
                 fieldTypes[field_name] = fieldType;
@@ -195,6 +241,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];
@@ -208,6 +258,7 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
                 fieldTypes,
                 scalarFields,
                 relationFields,
+                noWriteFields,
             };
         }
     }
@@ -450,7 +501,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))
@@ -473,12 +524,159 @@ 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}.`);
             }
         }
     }
+    /**
+     * Authorizes every relation a write establishes. Relationship authorization
+     * lives entirely in the `connect` action — create conditions judge a model's
+     * own scalar fields only.
+     *
+     * Runs on create AND update: a `create` can nest relation writes or set raw
+     * FKs; an `updateMany` (scalar-only) can re-point a raw FK. Both go through
+     * the same `connect` authorization.
+     *
+     *   - 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, trustedFk) {
+        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) {
+                    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
+                let value = row[key];
+                if (value && typeof value === 'object' && 'set' in value)
+                    value = value.set; // update form: { set: x }
+                if (value === undefined || value === null)
+                    continue;
+                await this.assertConnectAllowed(modelName, fk.field, fk.model, { [fk.foreignKey]: value }, user, userRole);
+            }
+        }
+    }
+    /** Authorizes each operator inside one relation's nested-write object. */
+    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. ` +
+                    `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', backFk);
+                    await this.enforceNestedWrites(relatedModel, child, user, userRole, backFk);
+                }
+            }
+            else {
+                for (const target of items) {
+                    await this.assertConnectAllowed(parentModel, field, relatedModel, target, user, userRole);
+                }
+            }
+        }
+    }
+    /** If `column` is the scalar FK backing a belongsTo relation, returns that relation's field + 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 { field: key, model: r.model, foreignKey: r.foreignKey };
+            }
+        }
+        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;
+    }
+    /**
+     * Authorizes attaching `relatedModel` (identified by `where`) through the
+     * `field` relation on `sourceModel`. Two rules can apply, evaluated against
+     * the candidate target row:
+     *   - a relation-scoped rule on the source (`sourceModel[role].relations[field].connect`)
+     *   - the target model's own rule (`relatedModel[role].connect`)
+     * When both exist they are ANDed (the relation rule can only strengthen).
+     * When only one exists it stands alone; when neither exists, default-deny.
+     */
+    async assertConnectAllowed(sourceModel, field, relatedModel, where, user, userRole) {
+        const normalizedName = relatedModel.toLowerCase().trim();
+        const exposedModels = (exports.CorePrismaContext.getStore()?.exposedModels || []).map((m) => m.toLowerCase());
+        if (exposedModels.includes(normalizedName))
+            return;
+        const relationRule = this.normalizedPermissionsConfig[sourceModel.toLowerCase().trim()]?.[userRole]?.['relations']?.[field]?.connect;
+        const targetRule = this.normalizedPermissionsConfig[normalizedName]?.[userRole]?.['connect'];
+        if (relationRule === undefined && targetRule === undefined) {
+            throw new common_1.ForbiddenException(`Not allowed to connect ${relatedModel} (via '${field}'): role ${userRole} has no 'connect' permission. ` +
+                `Declare it on ${relatedModel}.${userRole}.connect, or scope it to this relation with ${sourceModel}.${userRole}.relations.${field}.connect.`);
+        }
+        // Collect the conditions each applicable rule imposes; an 'ALL' or
+        // condition-less rule constrains nothing. The target must satisfy every
+        // collected condition (AND — the relation rule strengthens the target's).
+        const conditionSets = [];
+        for (const rule of [relationRule, targetRule]) {
+            if (rule === undefined || rule === 'ALL')
+                continue;
+            const conditions = rule.conditions;
+            if (conditions) {
+                conditionSets.push(PrismaService_1._buildConditions(Array.isArray(conditions) ? { AND: conditions } : conditions, user));
+            }
+        }
+        if (conditionSets.length === 0)
+            return; // every applicable rule is unconditional
+        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 || {}, ...conditionSets] } });
+        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
@@ -512,14 +710,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;
             }
@@ -527,7 +761,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;
                     }
@@ -538,16 +772,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;
         }
@@ -600,26 +832,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/README.md

@@ -0,0 +1,22 @@
+# 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`), 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.
+- **[authentication.md](./authentication.md)** — the built-in `/auth` surface, and **how to override framework internals** (extend the exported `AuthController`/`AuthService`/`RegisterDto`/Passport strategies and register your own at the same prefix via `AuthModule.forRoot({ controller: false })`) — e.g. adding `name` to registration.
+- **[graphql.md](./graphql.md)** — the **read-only** GraphQL API generated from your schema: queries, nested selections, and how ABAC filters them.
+- **[limitations.md](./limitations.md)** — **known limitations and features that are NOT ready for use** (e.g. `aggregate`, GraphQL writes). Read this before relying on any method not covered in the guides above.
+
+## 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.

package/docs/authentication.md

@@ -0,0 +1,220 @@
+# Authentication & overriding framework internals
+
+The framework ships a working auth surface. When you need to change part of it —
+add a field to registration, add endpoints, swap a Passport strategy — you don't
+fork it: you **extend the exported classes and register your own versions**. This
+page shows the pattern (auth is the main example, but it applies to any exported
+framework class).
+
+---
+
+## What `AuthModule` provides
+
+**Always wire it as `AuthModule.forRoot()`** — importing the bare `AuthModule`
+registers nothing (all wiring lives in `forRoot()` so the controller can be
+conditionally omitted; see the override section). `AuthModule.forRoot()` registers,
+under the `/auth` prefix:
+
+| Route | Guard | Body |
+|---|---|---|
+| `POST /auth/register` | — | `RegisterDto` (`email`, `password`) |
+| `POST /auth/login` | `LocalAuthGuard` | credentials |
+| `POST /auth/login/jwt` | `LocalAuthGuard` | credentials → tokens |
+| `POST /auth/refresh` | `RefreshTokenGuard` | refresh token |
+| `POST /auth/logout` · `logout/jwt` | `AuthenticatedGuard` | — |
+| `GET /auth/me`, `GET/POST /auth/sessions…` | `AuthenticatedGuard` | — |
+
+plus the providers (all **global**): `AuthService`, the Passport strategies
+(`LocalStrategy`, `JwtStrategy`, `RefreshTokenStrategy`), the guards
+(`LocalAuthGuard`, `JwtAuthGuard`, `AuthenticatedGuard`, `RefreshTokenGuard`,
+`SessionAuthGuard`), and `SessionSerializer`.
+
+**Registration is intentionally narrow.** `RegisterDto` accepts only `email` +
+`password`, and `AuthService.register` creates the user with `BYPASS_FILTERING`
+(it's an unauthenticated flow, so ABAC create-enforcement can't gate it). The
+`RegisterDto` whitelist is therefore the *only* thing controlling which fields a
+sign-up may set — which is exactly why widening it is a deliberate override, not
+a config toggle.
+
+All of these are exported from the package root — **import from
+`@appxdigital/appx-core`, never from `@appxdigital/appx-core/dist/...`** (deep
+paths are internal and can move between versions):
+
+```ts
+import {
+  AuthModule, AuthController, AuthService,
+  RegisterDto, UserDto, AuthField,
+  LocalStrategy, JwtStrategy, RefreshTokenStrategy,
+} from '@appxdigital/appx-core';
+```
+
+---
+
+## The override pattern
+
+To replace or extend an auth endpoint **at the same `/auth` prefix**:
+
+1. **Extend** the framework class (controller / service / strategy).
+2. Put your version in **your own module**.
+3. Import **`AuthModule.forRoot({ controller: false })`** — this keeps every auth
+   provider global but drops the built-in `AuthController`, so *your* controller
+   owns `/auth` with no duplicate route.
+4. Register your module in `AppModule` (in place of a bare `AuthModule`).
+
+```ts
+// app.module.ts
+@Module({
+  imports: [
+    AppxCoreModule.forRoot(PermissionsConfig),
+    AuthModule.forRoot({ controller: false }), // providers only, no built-in controller
+    MyAuthModule,                              // your controller/service live here
+    // …
+  ],
+})
+export class AppModule {}
+```
+
+```ts
+// my-auth.module.ts
+@Module({
+  controllers: [MyAuthController],
+  providers: [/* MyAuthService, MyLocalStrategy, … as needed */],
+})
+export class MyAuthModule {}
+```
+
+> **Why `forRoot({ controller: false })`?** If the built-in controller *and* your
+> own `/auth` controller are both registered, you get two handlers for the same
+> routes (Express runs the first-registered, so the base `RegisterDto` would win
+> and reject your extra fields). `forRoot({ controller: false })` drops the built-in
+> controller while keeping every provider global, so your controller takes over
+> cleanly. Use plain `AuthModule.forRoot()` (no options) when you're *not*
+> overriding the controller.
+
+---
+
+## Recipe 1 — add a field to registration (e.g. `name`)
+
+Extend `RegisterDto`, then override the inherited `register` handler:
+
+```ts
+// register-local.dto.ts
+import { RegisterDto } from '@appxdigital/appx-core';
+import { IsOptional, IsString } from 'class-validator';
+
+export class RegisterLocalDto extends RegisterDto {
+  @IsOptional()
+  @IsString()
+  name?: string;
+}
+```
+
+```ts
+// my-auth.controller.ts
+import { Body, Controller, Post } from '@nestjs/common';
+import { AuthController } from '@appxdigital/appx-core';
+import { RegisterLocalDto } from './register-local.dto';
+
+@Controller('auth')
+export class MyAuthController extends AuthController {
+  @Post('register')
+  async register(@Body() dto: RegisterLocalDto) {
+    return this.authService.register(dto); // authService is `protected` on AuthController
+  }
+}
+```
+
+`AuthService.register` spreads the DTO straight into the user create, so `name`
+persists (your `User` model must have the column). Everything else on
+`AuthController` — login, refresh, sessions — is inherited unchanged. The global
+validation pipe now validates the body against `RegisterLocalDto`, so `name` is
+accepted and any *other* unknown field still `400`s.
+
+> Keep registration a **narrow allowlist** — only add fields a self-service
+> sign-up should legitimately set. Never widen it to privileged columns (`role`,
+> tenant, ownership ids); mark those `/// @NoWrite` and set them server-side.
+
+---
+
+## Recipe 2 — extend the service (add methods / change behaviour)
+
+Extend `AuthService` and forward its constructor. Its signature is
+`(userService, prisma, jwtService, configService)`:
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { AuthService, PrismaService } from '@appxdigital/appx-core';
+import { UserService } from '../user/user.service';
+import { ConfigService } from '@nestjs/config';
+import { JwtService } from '@nestjs/jwt';
+
+@Injectable()
+export class MyAuthService extends AuthService {
+  constructor(
+    userService: UserService,
+    prisma: PrismaService,
+    jwtService: JwtService,
+    configService: ConfigService,
+  ) {
+    super(userService, prisma, jwtService, configService);
+  }
+
+  async handleForgotPassword(email: string) { /* … */ }
+}
+```
+
+Provide `MyAuthService` in your module and inject it in your controller
+(`super(myAuthService)` if the controller extends `AuthController`). Because you
+imported `AuthModule.forRoot({ controller: false })`, `UserService`, `JwtService`,
+`PrismaService`, and `ConfigService` are all already available to inject.
+
+---
+
+## Recipe 3 — override a Passport strategy
+
+The built-in `LocalStrategy` reads the username/password field names from
+`@AuthField(...)` metadata on `UserDto` and delegates to
+`AuthService.validateUser`. To change credential validation, extend it (or
+`JwtStrategy` / `RefreshTokenStrategy`) and provide your version:
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { LocalStrategy } from '@appxdigital/appx-core';
+
+@Injectable()
+export class MyLocalStrategy extends LocalStrategy {
+  async validate(username: string, password: string) {
+    // custom checks, then fall back to the framework behaviour:
+    return super.validate(username, password);
+  }
+}
+```
+
+```ts
+@Module({
+  controllers: [MyAuthController],
+  providers: [MyLocalStrategy], // Passport picks up the last-registered strategy of this name
+})
+export class MyAuthModule {}
+```
+
+> Passport registers strategies by name. Providing your own `LocalStrategy`
+> subclass in your module (with `AuthModule.forRoot({ controller: false })` for
+> the rest) makes yours the active `local` strategy.
+
+---
+
+## The general principle
+
+This isn't auth-specific. Every framework class you might need to specialise is
+exported from `@appxdigital/appx-core`. To override inner functionality:
+
+1. **Extend** the exported class.
+2. **Provide** your subclass in your own module (a subclass provider shadows the
+   base where you inject it).
+3. When the framework module would *also* register the thing you're replacing
+   (a controller, a route), import it in a mode that omits that piece — e.g.
+   `AuthModule.forRoot({ controller: false })` — so there's no duplicate.
+
+If a class you need to extend isn't exported, that's a framework gap — open it
+rather than deep-importing from `dist/`.