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

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.
@@ -43,7 +54,7 @@ A scalar field is included unless it is: the primary key (`@id`), a server-manag
 
 ### 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 +89,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';

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,20 @@ Prereleases are excluded from normal semver range resolution, so a project on
 
 ---
 
+## [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/docs/README.md

@@ -0,0 +1,20 @@
+# 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.
+- **[data-access.md](./data-access.md)** — how you talk to the database: the Prisma proxy (`prisma.model.*`), how ABAC filtering and field omission are enforced on every call, the redirected single-record methods, relation behaviour, bypass hatches, and transactions.
+- **[graphql.md](./graphql.md)** — the **read-only** GraphQL API generated from your schema: queries, nested selections, and how ABAC filters them.
+- **[limitations.md](./limitations.md)** — **known limitations and features that are NOT ready for use** (e.g. `aggregate`, GraphQL writes). Read this before relying on any method not covered in the guides above.
+
+## The one-paragraph mental model
+
+AppX Core wraps the Prisma client in a proxy that enforces **attribute-based access control (ABAC)** on every database call. You declare row-level and field-level rules once in `permissions.config.ts`; the proxy injects them into each query automatically based on the current request's user role. Controllers/resolvers are generated from your Prisma schema. The rules of the road: **go through the proxy** (`prismaService.model.*`) so ABAC applies, **declare a permission for every model/role/action** you want to allow (everything else is default-denied), and **check [limitations.md](./limitations.md)** before using a method.
+
+## Conventions used in these docs
+
+- `$USER_ID` refers to `PermissionPlaceholder.USER_ID` — a placeholder replaced with the current user's id at query time.
+- "the proxy" means the `PrismaService` client returned by `prismaService.model` (and the `prisma.user` / `prisma.session` / `prisma.userRefreshToken` accessors).
+- "default-deny" means: if no rule matches, the request is refused (a `403` at the guard, or a thrown `HttpException` at the proxy) — never silently allowed.

package/docs/data-access.md

@@ -0,0 +1,108 @@
+# Data Access & ABAC Enforcement
+
+How you read and write the database, and exactly what the proxy does to every call. Pair this with [permissions.md](./permissions.md) (which defines the rules) and [limitations.md](./limitations.md) (what not to use yet).
+
+---
+
+## Always go through the proxy
+
+Inject `PrismaService` and use `prismaService.model.*`:
+
+```ts
+const projects = await this.prisma.model.project.findMany({ where: { status: 'active' } });
+```
+
+`prismaService.model` returns a proxied Prisma client. **Only calls through this proxy get ABAC.** If you reach the raw Prisma client directly (a second `PrismaClient`, raw SQL, `$queryRaw`), you bypass all filtering and field omission. There is **no defence-in-depth at the controller layer** for row rules — the proxy is the single enforcement point.
+
+There are also three narrow typed accessors — `prismaService.user`, `prismaService.session`, `prismaService.userRefreshToken` — which are the proxied delegates for those framework models (used by auth flows, often with the bypass options below).
+
+Model names are **case-insensitive** at the proxy (`prisma.model.project` / `prisma.model.Project` resolve the same delegate and the same config).
+
+---
+
+## What the proxy does on every call
+
+For each `prisma.model.<model>.<method>(args, options?)`:
+
+1. **Field omission** (reads only) — removes columns the role may not read (`/// @Role(...)`), recursing into nested `select`/`include` at every depth.
+2. **Condition injection** — looks up `PermissionsConfig[model][role][action]`; if `'ALL'`, no filter; if `{ conditions }`, `AND`-merges them into your `where` (so your filter and the permission filter both apply); if nothing (after fallbacks), throws `403`.
+3. **Executes** the (possibly rewritten) query.
+
+The role comes from the current request's user (`GUEST` if unauthenticated). Requests run inside an async context established by the framework's middleware/interceptor.
+
+---
+
+## Method contract (important)
+
+The proxy can only enforce ABAC on methods that accept a `where` it can inject conditions into. Single-record methods keyed on a unique id cannot, so they are **re-aliased** — in both the TypeScript types and at runtime:
+
+| You call | Actually runs | Params / return you get |
+|---|---|---|
+| `findUnique()` | `findFirst()` | non-unique `where`, nullable result |
+| `findUniqueOrThrow()` | `findFirstOrThrow()` | non-unique `where` |
+| `update()` | `updateMany()` | `{ where, data }`, returns `{ count }` |
+| `delete()` | `deleteMany()` | `{ where }`, returns `{ count }` |
+
+**Consequences:**
+
+- `update()` / `delete()` return `{ count }`, **not** the affected record. Re-read if you need the row.
+- These operate on **all matching rows**, not one — always pass a `where`. With ABAC conditions injected, a cross-owner `update({ where: { id } })` simply affects `{ count: 0 }` rather than erroring.
+- The TypeScript types reflect this: calling `update()` with a lone unique `where` and expecting a record back is a **compile error**, not a runtime surprise.
+
+Use `findMany` / `findFirst` / `findFirstOrThrow` / `updateMany` / `deleteMany` directly if you prefer the explicit names.
+
+---
+
+## Field omission (`@Role`)
+
+A column annotated `/// @Role(ADMIN)` is returned only to roles in the list; for others the proxy drops it from the `select` so it comes back `undefined`. `/// @Role(none)` hides it from everyone (e.g. `password`).
+
+- Omission applies to nested relations too: `include: { owner: true }` won't leak `owner`'s `@Role`-restricted fields to an unauthorized role.
+
+---
+
+## Relations in conditions and includes
+
+- **Row conditions** may traverse relations to any depth: `{ conditions: { task: { project: { ownerId: $UID } } } }`. Both `belongsTo` (to-one) and `hasMany` / M:N (`some`/`every`/`none`) are supported. Note Prisma semantics: `every` is **true on an empty list**.
+- **Including a to-one relation is inner-join filtered.** When you `include`/`select` a `belongsTo` relation, the related model's read rules are merged into the **parent** row's `where`:
+  - If the related model has **no** read rule for the role, including it throws `403`. Grant a read rule on every model you expose through an `include`.
+  - If the related row exists but doesn't satisfy the rule, the **whole parent row is dropped** (`findFirst` → `null`, `findMany` → the row is omitted). The parent is **not** returned with the relation set to `null`. In short: you can't see a row whose related record you're not allowed to see. This is intentional and fails closed.
+- **To-many relations are filtered in place**: the parent is kept, and the child list is narrowed to the rows the caller may read (possibly empty).
+
+---
+
+## Bypass hatches
+
+Use sparingly and deliberately; each disables part of the protection.
+
+- **Per-call options** — `prisma.<accessor>.<method>(args, { BYPASS_FILTERING, BYPASS_OMISSION })`. `BYPASS_FILTERING` skips condition injection (and create-enforcement); `BYPASS_OMISSION` skips field omission. Available on the typed accessors (`prisma.user`, `prisma.session`, `prisma.userRefreshToken`).
+- **`@ExposeModels(...)` / `@Permission(action, [models])`** — expose models for a request so they skip row/field filtering, scoped to the handler. See [permissions.md](./permissions.md).
+- **`prismaService.withExposedModels(models, async () => { ... })`** — service-level scoped exposure for a block of code (e.g. registration pre-checks). Model names are lowercased/case-insensitive.
+
+Framework flows that must write without a permission (registration, sessions, tokens) use `BYPASS_FILTERING`.
+
+---
+
+## Creates
+
+`create` / `createMany` can't push conditions into a `WHERE`, so the proxy **validates the incoming data against the create rule's `conditions` before insert**:
+
+- Own-scalar conditions are checked against `data`; `belongsTo` relation conditions are checked by looking up the referenced parent.
+- A model/role with **no** `create` permission is **default-denied** (`403`).
+- It **fails closed**: unsupported condition shapes for create (list-relation `some`/`every`/`none`, exotic operators) throw rather than silently allow. For those, use `setUserIdField` to set an owner id server-side and validate inputs in DTOs.
+- In development only, a warning fires if a just-created row wouldn't satisfy the model's *read* rule (i.e. the creator couldn't read it back).
+
+---
+
+## Transactions
+
+Set `USE_TRANSACTION=true` (env) to wrap each request handler in a Prisma `$transaction`; per-endpoint control via the transaction metadata. The framework commits the transaction **before** sending the HTTP response, so a read-after-write in a dependent request can't miss the write. Inside a transaction the proxy uses the request's transaction client automatically.
+
+---
+
+## Blocked / redirected methods — quick reference
+
+- `findUnique` / `findUniqueOrThrow` → run as `findFirst` / `findFirstOrThrow` (see contract above).
+- `update` / `delete` → run as `updateMany` / `deleteMany`.
+- Raw client access, `$queryRaw`, a second `PrismaClient` → **not proxied, no ABAC**. Don't use them for user-scoped data.
+- `aggregate` → see [limitations.md](./limitations.md) (not ready).

package/docs/graphql.md

@@ -0,0 +1,72 @@
+# GraphQL (read API)
+
+AppX Core can expose a **read-only GraphQL API** generated from your Prisma schema. Queries run through the same ABAC proxy as REST, so row-level filtering and field omission apply automatically.
+
+> **Scope:** only **read** queries are available today — `findAll<Model>s`, `findOne<Model>`, `findFirst<Model>`. Writes (create/update/delete mutations) are **not available yet**; see [limitations.md](./limitations.md). Use the REST CRUD endpoints for writes.
+
+---
+
+## Queries
+
+For each model, the generated schema provides:
+
+| Query | Returns |
+|---|---|
+| `findAll<Model>s(...)` | a list |
+| `findFirst<Model>(...)` | the first match, or `null` |
+| `findOne<Model>(where: {...})` | a single record, or `null` |
+
+```graphql
+query {
+  findAllProjects(where: { status: "active" }) {
+    id
+    name
+  }
+}
+```
+
+These route through `PrismaService`, so the caller's role and the rules in `permissions.config.ts` are enforced exactly as they are for REST reads (see [permissions.md](./permissions.md) and [data-access.md](./data-access.md)). A user only ever receives rows and fields their role is permitted to read.
+
+---
+
+## Nested queries
+
+You can select related models inline, to any depth:
+
+```graphql
+query {
+  findAllProjects {
+    id
+    name
+    tasks {
+      title
+      assignee {
+        name
+      }
+    }
+  }
+}
+```
+
+Nested selections are **ABAC-filtered** just like the top level.
+
+> **Caveat — inaccessible nested data comes back empty, not as an error.** If the current user isn't allowed to read a related record, it is simply filtered out:
+> - a **to-many** relation (`tasks`, `members`, …) returns an **empty list** for the parts the user can't see;
+> - an **inaccessible to-one** relation causes the **parent row to be omitted** from the result (you can't see a row whose related record you aren't allowed to read).
+>
+> No exception is thrown — the data you're not entitled to just isn't there. Design your queries and UI to treat "empty" as "not visible to you", not "does not exist".
+
+---
+
+## Field-level visibility
+
+Columns annotated `/// @Role(...)` follow the same rules as everywhere else: a role that can't read a field won't receive it in the GraphQL response, at the top level and nested. See [permissions.md](./permissions.md#field-level-control).
+
+---
+
+## Not available yet
+
+- **Mutations** (create/update/delete) — use REST.
+- **`aggregate`** — not ready; see [limitations.md](./limitations.md).
+
+Always let the generated resolvers (which go through `PrismaService`) serve the data — a custom resolver that reaches the raw Prisma client would not get ABAC.

package/docs/limitations.md

@@ -0,0 +1,55 @@
+# Known Limitations & Not-Ready Features
+
+Read this before using any method or surface not explicitly covered in [permissions.md](./permissions.md) / [data-access.md](./data-access.md). Items here are either **not ready for use**, or **behave differently from vanilla Prisma** in ways you must account for.
+
+---
+
+## Not ready — do not use yet
+
+### `aggregate`
+
+`prisma.model.<model>.aggregate(...)` is **not a supported ABAC action**. There is no `aggregate` permission and no fallback to a read rule, and the field-omission logic isn't designed for aggregate argument shapes. Its ABAC behaviour is undefined/untested — **avoid it for user-scoped data**.
+
+- Need a count? Use `count(...)` — it **is** supported and falls back to your `findMany` rule.
+- Need a genuine aggregate behind trusted access? Compute it inside a `withExposedModels(...)` block (or a bypass) with your own authorization, and never expose it to untrusted roles until aggregate ABAC lands.
+
+### GraphQL — writes and `aggregate`
+
+GraphQL currently supports **read queries only** (`findAll<Model>s` / `findFirst<Model>` / `findOne<Model>`), with ABAC applied. See **[graphql.md](./graphql.md)** for how to use it, including nested queries.
+
+- **Mutations (create / update / delete) are not available yet** — use the REST CRUD endpoints for writes.
+- **`aggregate` is not ready** — same caveat as REST above.
+
+Let the generated resolvers serve the data (they go through `PrismaService`); a custom resolver that reaches the raw Prisma client would not get ABAC.
+
+---
+
+## Behaves differently from vanilla Prisma
+
+### Single-record methods are redirected
+
+`findUnique` → `findFirst`, `findUniqueOrThrow` → `findFirstOrThrow`, `update` → `updateMany`, `delete` → `deleteMany` (types + runtime). `update()`/`delete()` return `{ count }`, not the record, and act on all matching rows. Full contract in [data-access.md](./data-access.md#method-contract-important).
+
+### Including an unreadable to-one relation drops the parent row
+
+`include`/`select` of a `belongsTo` relation whose target the caller can't read removes the **whole parent row** (returns `null` / omits it), rather than nulling just the relation. To-many relations filter in place and keep the parent. Fails closed; intentional. See [data-access.md](./data-access.md#relations-in-conditions-and-includes).
+
+### `_count` pseudo-field filtering is not implemented
+
+You can `select: { _count: ... }`, but ABAC conditions are **not** applied inside a `_count` sub-selection. Don't rely on `_count` to reflect only rows the caller may see.
+
+---
+
+## Sharp edges to know about
+
+- **`restrictedFields` strips silently.** Listed fields are removed from the request body with no `400`. It only affects fields that are present in the generated DTO (not `/// @NoWrite` ones). Decide per model whether silent stripping is acceptable.
+- **Per-call bypass options are only on three accessors.** `{ BYPASS_FILTERING, BYPASS_OMISSION }` are available on `prismaService.user` / `.session` / `.userRefreshToken`. For an unfiltered read of another model, use `withExposedModels([...])` or `@ExposeModels(...)`, not a per-call option on `prisma.model.<x>`.
+- **Role strings are not type-checked.** `PermissionsConfig` keys are plain strings; a typo (`ADIMN`) silently yields "no permissions" → default-deny for that role. Double-check role spelling against your `Role` enum.
+- **No audit logging of denials.** A refused request returns `403` but emits no structured audit event; per-request diagnostics are opt-in via `prismaService.debugQueries(true)`.
+- **Exposed models are a full bypass.** `@ExposeModels` / `@Permission(a, [models])` / `withExposedModels` disable row *and* field filtering for the listed models within that scope. Keep the scope as narrow as possible.
+
+---
+
+## Reporting
+
+If the framework does something these docs don't describe, that's a documentation or framework bug — surface it rather than coding around it. These docs are the source of truth.

package/docs/permissions.md

@@ -0,0 +1,137 @@
+# Permissions & Authorization
+
+How AppX Core decides **who may do what**. Two layers cooperate:
+
+1. **`RbacGuard`** (route level) — checks that the caller's role has *a* permission for the requested action on the model. Coarse allow/deny; does **not** evaluate row conditions.
+2. **The Prisma proxy** (data level) — injects the row-level `conditions` and applies field-level omission on every query. This is the real enforcement layer. See [data-access.md](./data-access.md).
+
+Both read the same `permissions.config.ts`.
+
+---
+
+## The permissions config
+
+Lives in `src/config/permissions.config.ts` and is passed to `AppxCoreModule.forRoot(PermissionsConfig)`.
+
+```ts
+import { PermissionPlaceholder, PermissionsConfigType } from '@appxdigital/appx-core';
+
+const $UID = PermissionPlaceholder.USER_ID;
+
+export const PermissionsConfig: PermissionsConfigType = {
+  Project: {                       // model name (matches the Prisma model)
+    ADMIN: {                       // role (matches your Role enum / role strings)
+      findMany: 'ALL',
+      create: 'ALL',
+      updateMany: 'ALL',
+      deleteMany: 'ALL',
+    },
+    USER: {
+      findMany: { conditions: { OR: [{ ownerId: $UID }, { members: { some: { userId: $UID } } }] } },
+      create:   { conditions: { ownerId: $UID } },
+      updateMany: { conditions: { ownerId: $UID } },
+    },
+    GUEST: {                       // unauthenticated requests — see "GUEST" below
+      findMany: 'ALL',
+    },
+  },
+};
+```
+
+Shape: `PermissionsConfig[Model][Role][action]`, where each `action` value is either:
+
+- **`'ALL'`** — unrestricted for that action, or
+- **`{ conditions: <where> }`** — an ABAC rule. `conditions` is Prisma `where`-syntax (`AND`/`OR`/`NOT`, relation filters `some`/`every`/`none`, operators `in`/`not`/`lt`/…). `$USER_ID` is substituted with the caller's id at query time.
+- Optionally with **`restrictedFields`** and/or **`setUserIdField`** (see below).
+
+**Model and role keys are matched case-insensitively** against the model name and the caller's role string.
+
+### Actions
+
+| Action | Triggered by |
+|---|---|
+| `findMany`, `findFirst` | reads |
+| `count` | counts |
+| `create`, `createMany` | inserts |
+| `updateMany` | updates (also what `update()` resolves to — see [data-access.md](./data-access.md)) |
+| `deleteMany` | deletes (also what `delete()` resolves to) |
+
+> `aggregate` is **not** a supported permission action yet — see [limitations.md](./limitations.md).
+
+### Action fallback chains
+
+To keep configs compact, a missing action falls back:
+
+- **`count` → `findMany` → `findFirst`** (reads share a rule).
+- **`findFirst` / `findUnique`-shape reads → `findMany`**.
+- **`createMany` → `create`**, **`updateMany` → `update`**, **`deleteMany` → `delete`** (a batch action inherits the singular rule).
+
+The `*Many` → singular fallback is **one-directional**: the singular is canonical. Declaring only `updateMany` does *not* enable `update`; declare `update` (or `create`/`delete`) and the `*Many` form is covered automatically. This holds in **both** the `RbacGuard` and the proxy.
+
+So a minimal USER config often needs just `findMany`, `create`, `update`, `delete`.
+
+### Field-level control
+
+- **`/// @Role(ADMIN)` on a schema column** — only listed roles can *read* that field. For everyone else the proxy omits it from results (it comes back `undefined`). `/// @Role(none)` hides it from all roles. Applies at every depth, including nested relation selections.
+- **`/// @NoWrite` on a schema column** — excludes the field from generated create/update DTOs (all roles).
+- **`restrictedFields: ['x', 'y']` on a permission action** — strips those keys from the incoming request body for that role+action (e.g. stop a role from setting `role`/`id`). Silent strip, not a `400`.
+- **`setUserIdField: 'ownerId'`** — the framework sets that field to the caller's id server-side on create (so a client can't forge ownership). Applied after `restrictedFields`, so it can't be clobbered.
+
+---
+
+## Decorators
+
+### `@Permission(action, exposeModels?)`
+
+Declares the action a route requires. Read by `RbacGuard` (enforces the role has the action) and by the interceptor (for `exposeModels`).
+
+```ts
+@Permission('findMany')
+@Get()
+list() { /* ... */ }
+```
+
+- `RbacGuard` looks up `PermissionsConfig[model][role][action]`; if absent (after fallbacks) it throws `403`. `model` comes from the controller's `entityName`.
+- **`RbacGuard` is auto-applied on `CoreController`** (all generated CRUD controllers). On a **custom** controller, add `@UseGuards(RbacGuard)` yourself if you want the action enforced.
+- The optional second argument exposes models for the request — see below.
+
+### `@ExposeModels(...models)`
+
+Exposes one or more models for the duration of the request **without** requiring a permission action.
+
+```ts
+@ExposeModels('user')      // no @Permission needed
+@Get('/auth/email-available')
+isEmailAvailable(@Query('email') email: string) { /* reads User unfiltered */ }
+```
+
+- Sets **no action**, so `RbacGuard` demands no permission (a public / `GUEST` route works with no `GUEST` rule for the model).
+- The listed models **skip row and field filtering for that request only** (scoped via async context — it does not make the model globally readable).
+- Case-insensitive: `@ExposeModels('User')` and `@ExposeModels('user')` are equivalent.
+- Combine with `@Permission(...)` if you also want an action check — exposed models from both decorators are merged.
+- This is a deliberate **bypass**. Use it narrowly (e.g. registration pre-checks); prefer real ABAC rules where feasible.
+
+> `@Permission(action, ['user'])` still exposes models exactly as before — `@ExposeModels` is the permission-free alternative, not a replacement.
+
+---
+
+## The GUEST (unauthenticated) flow
+
+A request with **no session and no valid JWT** is treated as the role **`GUEST`**:
+
+- The global `UserPopulationGuard` never blocks — it populates `req.user` from a `Bearer` JWT if present, otherwise leaves the request unauthenticated and passes through.
+- `RbacGuard` defaults the role to `'GUEST'` and looks up `PermissionsConfig[model]['GUEST'][action]`. If you declared a `GUEST` rule, the route is allowed; otherwise it is default-denied (`403`).
+- The proxy likewise resolves the role to `GUEST` and applies `GUEST` conditions (or default-denies).
+
+So to allow public access to a model, add a `GUEST` block to its config. To allow public access to a route that reads a model you *don't* want generally public, use `@ExposeModels(...)` instead.
+
+---
+
+## Default-deny
+
+If a model/role/action has no rule (after fallbacks) and the model is not exposed:
+
+- `RbacGuard` throws `ForbiddenException` (`403`).
+- The proxy throws `HttpException(403)`.
+
+There is no "allow by omission". A typo in a role or model key means that path is denied.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@appxdigital/appx-core",
-    "version": "0.1.121-beta.8",
+    "version": "0.1.121-beta.9",
     "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",
@@ -100,6 +100,7 @@
     },
     "files": [
         "dist",
+        "docs",
         "CHANGELOG.md",
         "PRERELEASES.md",
         "RELEASING.md"