@appxdigital/appx-core 0.1.121-beta.14 → 0.1.121-beta.16

package/CHANGELOG.md

@@ -51,6 +51,7 @@ 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
 
@@ -132,6 +133,17 @@ async update(@Param('id') id: string, @Body() data: Update<Model>Dto) { return s
 >
 > **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.
 - 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,47 @@ 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

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);

package/docs/README.md

@@ -7,6 +7,7 @@ Authoritative usage documentation for `@appxdigital/appx-core`. **This folder is
 - **[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.
 

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/`.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@appxdigital/appx-core",
-    "version": "0.1.121-beta.14",
+    "version": "0.1.121-beta.16",
     "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",