@appxdigital/appx-core 0.1.120 → 0.1.121-beta.11

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/dtos.md

@@ -0,0 +1,163 @@
+# Generated CRUD DTOs
+
+`appx generate` emits a `class-validator` DTO for each model's create and update actions. Combined with the global validation pipe (`whitelist` + `forbidNonWhitelisted`), these DTOs are what stop CRUD `POST`/`PUT` endpoints from accepting arbitrary fields (mass-assignment). This page covers what they contain, how to customize them, and — the common question — **how to remove a field**.
+
+---
+
+## Two files per action
+
+For every model + action there are two files:
+
+| File | Owned by | Edit it? |
+|---|---|---|
+| `src/generated/dto/<model>/<action>-<model>.generated.dto.ts` | the generator — **overwritten** every `appx generate` (gitignored) | **Never.** |
+| `src/modules/<model>/dto/<action>-<model>.dto.ts` | you — generated **once**, never overwritten | **Yes — customize here.** |
+
+The generated controller imports the **hand-owned** subclass, which by default just extends the base:
+
+```ts
+import { CreateTaskGeneratedDto } from '../../../generated/dto/task/create-task.generated.dto';
+
+export class CreateTaskDto extends CreateTaskGeneratedDto {}
+```
+
+Put all your customizations in that subclass. Editing the `.generated.dto.ts` base is pointless — it's regenerated from the schema.
+
+---
+
+## What the base contains (writable-field policy)
+
+A scalar field is **included** unless it is:
+
+- the primary key (`@id`),
+- a server-managed timestamp (`@default(now())` / `@updatedAt`),
+- annotated `/// @NoWrite`,
+- annotated `/// @Role(none)`.
+
+**Relation navigation fields are excluded**; their scalar foreign keys are kept. Types map to validators: enums → `@IsEnum`, scalars → `@IsString`/`@IsInt`/`@IsBoolean`/`@IsNumber`/`@IsDateString`, `Json`/`Bytes` → `@Allow()`.
+
+> Because relations are excluded, generic CRUD endpoints accept **flat** writes (scalars + FK ids), not nested relation writes. See [Relations & nested writes](#relations--nested-writes) below.
+
+---
+
+## How to remove a field
+
+There are three ways, at different scopes. Pick the narrowest one that fits.
+
+| Mechanism | Scope | Where you declare it |
+|---|---|---|
+| `OmitType(GeneratedDto, ['field'])` | this one endpoint's DTO | the hand-owned `*.dto.ts` |
+| `/// @NoWrite` (or `/// @Role(none)`) | every generated DTO, every role | the Prisma schema |
+| `restrictedFields: ['field']` | a specific role + action (runtime strip) | `permissions.config.ts` |
+
+### 1. `OmitType` — remove a field for one endpoint
+
+The subclass extends a **stripped** version of the base. `OmitType` (and its siblings) come from `@nestjs/mapped-types` (already a framework dependency):
+
+```ts
+import { OmitType } from '@nestjs/mapped-types';
+import { CreateTaskGeneratedDto } from '../../../generated/dto/task/create-task.generated.dto';
+
+// drop `reviewerId` from what this endpoint accepts
+export class CreateTaskDto extends OmitType(CreateTaskGeneratedDto, ['reviewerId'] as const) {}
+```
+
+With the whitelist pipe on, a removed field is no longer part of the DTO, so a body that includes it is rejected (`forbidNonWhitelisted`) rather than written.
+
+Related helpers, all of which preserve validation metadata:
+
+- `PickType(Base, ['a', 'b'] as const)` — keep only these fields (inverse of `OmitType`).
+- `PartialType(Base)` — make every field optional (handy for update DTOs).
+- `IntersectionType(A, B)` — merge two DTOs.
+
+### 2. `/// @NoWrite` — remove a field everywhere
+
+Annotate the column in the Prisma schema and regenerate. The field is excluded from **all** generated create/update DTOs for **all** roles. Use this for fields that should never be client-writable (e.g. an internal status). `/// @Role(none)` has the same write-exclusion effect (and also hides the field on read).
+
+```prisma
+model Task {
+  internalRef String? /// @NoWrite
+}
+```
+
+### 3. `restrictedFields` — remove a field per role
+
+Strip specific keys from the body for a given role + action, at runtime, from `permissions.config.ts`:
+
+```ts
+Task: {
+  USER: { create: { conditions: { ... }, restrictedFields: ['status'] } },
+}
+```
+
+Note: `restrictedFields` **strips silently** (no `400`), and only affects fields that are present in the DTO to begin with. See [permissions.md](./permissions.md#field-level-control).
+
+---
+
+## How to add validation
+
+Add decorated properties (or re-declare an existing one with stricter rules) on the subclass:
+
+```ts
+import { IsEmail, MaxLength } from 'class-validator';
+import { CreateUserGeneratedDto } from '../../../generated/dto/user/create-user.generated.dto';
+
+export class CreateUserDto extends CreateUserGeneratedDto {
+  @IsEmail()
+  declare email: string;
+
+  @MaxLength(120)
+  declare name?: string;
+}
+```
+
+You can combine this with `OmitType`/`PickType` — extend the transformed base, then add rules.
+
+---
+
+## Relations & nested writes
+
+Generated **create** DTOs expose each relation as a nested-write member that accepts an explicit allowlist of operators — **`create` and `connect` only** — each authorized by ABAC. Other operators (`set`, `disconnect`, `update`, `upsert`, `delete`, …) are deliberately **not** emitted, so the validation pipe rejects them; the proxy rejects them defensively too. Both layers fail closed.
+
+- **`create`** — creates the related record(s). Authorized against the related model's **`create`** rule (recursively, so deeper nesting is checked too). The back-reference foreign key is set automatically by the parent write and is omitted from the nested DTO.
+- **`connect`** — links existing record(s) by their unique fields. Authorized against the related model's dedicated **`connect`** permission — see [permissions.md](./permissions.md). A `connect` rule is **required**; being able to *read* a record does not authorize associating it. No `connect` rule ⇒ the connect is refused.
+
+So a nested write succeeds only when it is an allowed operator **and** the caller passes the related model's rule.
+
+**Only `create()` carries nested writes.** `update` resolves to `updateMany`, whose payload is scalar-only (a Prisma constraint), so nested writes are not available on update — do the update and the relation change as separate operations, or in an explicit endpoint.
+
+Example — create a project with a new task and connect existing tags:
+
+```jsonc
+POST /projects
+{
+  "name": "Alpha",
+  "ownerId": 1,
+  "tasks": { "create": [{ "title": "kickoff" }] },  // requires Task.create rule
+  "tags":  { "connect": [{ "id": 7 }] }             // requires Tag.connect rule
+}
+```
+
+**Keep `forbidNonWhitelisted: true` on** so a disallowed operator (e.g. `set`) **fails loud** with a `400`. Never run `whitelist` in strip-only mode on writes — it would silently drop the payload.
+
+### Nesting depth: one level over HTTP CRUD
+
+The generated nested-write DTOs go **one level deep**. A nested `create` DTO contains the related model's **scalar fields only** (plus its `connect`) — it does **not** expose that model's *own* relations. This is deliberate: it keeps the generated DTOs free of circular references.
+
+Consequence for CRUD requests:
+
+- **One level works:** `project.create` with `tasks: { create: [...] }` or `tags: { connect: [...] }`. ✅
+- **Two+ levels are rejected with `400`:** e.g. `project.create` → `tasks: { create: [{ title, comments: { create: [...] } }] }`. The inner `comments` key is not on the (scalar-only) task nested-create DTO, so `forbidNonWhitelisted` rejects it. This fails **loud**, never silently.
+
+Note the two layers behave differently on purpose:
+
+- **The proxy enforcement is fully recursive** — it authorizes nested `create`/`connect` at *any* depth (each level checked against that model's `create` / `connect` rule). So deep nesting is safe wherever it can reach the proxy.
+- **The generated DTOs cap the HTTP surface at one level.** Deep nesting simply isn't expressible through generic CRUD.
+
+**To do multi-level nested writes, use an explicit controller/service method** that calls `prismaService.model.<x>.create(...)` with the deep payload — the proxy still enforces the `create`/`connect` allowlist recursively there. Do not try to widen the generated DTOs to accept deeper nesting.
+
+---
+
+## After changing the schema
+
+Re-run `npx appx generate`. The `.generated.dto.ts` bases update; your hand-owned `*.dto.ts` subclasses are left untouched (so your `OmitType`/validation customizations survive). Review new/removed fields in the regenerated bases.

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,59 @@
+# 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.
+
+### Nested writes over HTTP CRUD are one level deep
+
+Generated CRUD accepts nested `create`/`connect` **one level deep only** — a `project.create` may nest tasks/tags, but not a task that itself nests comments (the second level `400`s under `forbidNonWhitelisted`). The proxy's authorization is recursive; the *DTO* surface is the cap, kept one level to avoid circular DTOs. For multi-level nested writes use an explicit endpoint that calls `prismaService.model.*.create(...)`. See [dtos.md](./dtos.md#nesting-depth-one-level-over-http-crud).
+
+---
+
+## Sharp edges to know about
+
+- **`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,155 @@
+# 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) |
+| `connect` | associating an existing record as a nested-write relation target — see below |
+
+> `aggregate` is **not** a supported permission action yet — see [limitations.md](./limitations.md).
+
+### The `connect` action
+
+When a `create` payload nests `{ relation: { connect: {...} } }` (linking an existing record), the framework checks the **target model's `connect` rule** — a **dedicated** action, separate from reads. This exists because *being able to see a record is not permission to associate it* (seeing a team ≠ being allowed to join it).
+
+```ts
+Team: {
+  USER: {
+    findMany: { conditions: { ... } },        // who can SEE a team
+    connect:  { conditions: { ownerId: $UID } } // who can ATTACH a team to something they're creating
+  },
+}
+```
+
+The `connect` rule's conditions are evaluated against the candidate record. **Default-deny, no fallback:** if the target model has no `connect` rule, the connect is refused. See [dtos.md](./dtos.md#relations--nested-writes) for the nested-write allowlist (`create` / `connect` only).
+
+### 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.
+
+> For the generated request-body DTOs — their structure, and the full set of ways to **remove or restrict a writable field** (`OmitType`, `/// @NoWrite`, `restrictedFields`) — see **[dtos.md](./dtos.md)**.
+
+---
+
+## 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.