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

package/CHANGELOG.md

@@ -0,0 +1,123 @@
+# Changelog
+
+All notable changes to `@appxdigital/appx-core` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project follows the `MAJOR.MINOR.PATCH` scheme in `package.json`.
+
+## How to read this file
+
+- **This file is the collapsed, production changelog** — one section per version published to the `latest` dist-tag. Granular per-build notes for `alpha`/`beta` prereleases live in [`PRERELEASES.md`](./PRERELEASES.md); the release process is documented in [`RELEASING.md`](./RELEASING.md).
+- **Every released version has a section.** Newest first.
+- **Changes that require action in an existing project are listed under `### Migration`** — copy-paste ready, small enough to hand to an AI coding agent. Items outside that block are drop-in.
+- **Scaffold-only changes** (files under `cli/scaffold/`) affect *new* projects created with `appx-core create`. Existing projects own their copies of those files and apply the migration by hand.
+
+---
+
+## [0.1.121] — 2026-07-14
+
+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.
+- **`buildCoreSessionOptions({ secret, store, cookieName?, ttlSeconds?, secure?, sameSite? })`** — builds hardened `express-session` options. Throws if `secret` is missing or `< 32` chars (no fallback); sets `cookie: { httpOnly, secure (prod), sameSite: 'lax', maxAge }`.
+- **`coreEnvFilePath()`** — returns `['.env.${NODE_ENV}', '.env']` (env-specific file wins, plain `.env` is a fallback) and throws if `NODE_ENV` is unset.
+- **Per-model DTO generation** (`appx generate`). Each model+action gets a `class-validator` DTO so generated controllers type their request body concretely and the whitelist pipe can strip unknown fields. Two files:
+  - `src/generated/dto/<model>/<action>-<model>.generated.dto.ts` — base class, **always overwritten**, under the gitignored `src/generated/`. Never hand-edit.
+  - `src/modules/<model>/dto/<action>-<model>.dto.ts` — a hand-owned subclass, generated **once**, for custom validation. The controller imports this.
+- **`/// @NoWrite` field annotation** — excludes a field from the generated create/update DTOs (all roles). Fields annotated `/// @Role(none)` are also treated as non-writable.
+- **Create-permission enforcement in the data-access proxy.** `create` / `createMany` validate that the incoming data satisfies the permission's `conditions` before insert (own-scalar fields against the data; relation conditions by looking up the referenced parent), and default-deny when the model/role has no `create` permission. A development-only warning fires when a created row would not satisfy the model's `find` conditions.
+- **`restrictedFields` on `create`** in `CoreController` (previously only `update`, which also read the wrong permission key so it never applied under `updateMany`).
+
+### Writable-field policy (generated DTOs)
+
+A scalar field is included unless it is: the primary key (`@id`), a server-managed timestamp (`@default(now())` / `@updatedAt`), `/// @NoWrite`, or `/// @Role(none)`. Relation navigation fields are excluded; their scalar foreign keys are kept. Enums map to `@IsEnum`, scalars to the matching `@IsString`/`@IsInt`/`@IsBoolean`/`@IsNumber`/`@IsDateString`; `Json`/`Bytes` use `@Allow()`.
+
+### Changed (scaffold — new projects only)
+
+- `main.ts` calls `setupCoreSecurity(app, { cors: { origin: corsOrigin, credentials: true } })`, builds session options via `buildCoreSessionOptions`, and reads `CORS_ORIGIN` from config.
+- `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)`.
+
+### Migration
+
+> **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
+import { setupCoreSecurity } from '@appxdigital/appx-core';
+// remove: app.useGlobalPipes(new ValidationPipe({ transform: true }));
+// remove: app.enableCors({ origin: 'http://localhost:3000', credentials: true });
+const corsOrigin = configService.get<string>('CORS_ORIGIN') ?? 'http://localhost:3000';
+setupCoreSecurity(app, { cors: { origin: corsOrigin, credentials: true } });
+```
+- Install Helmet: `npm install helmet@^8.0.0` (applied automatically by `setupCoreSecurity`; tune with `{ helmet: {...} }`, disable with `{ helmet: false }`).
+- If you register a `ValidationPipe` with custom options, pass them through: `setupCoreSecurity(app, { validationPipe: { /* overrides */ } })`.
+- With `whitelist` + `forbidNonWhitelisted`, body properties not declared on a `class-validator` DTO are rejected (`400`). Confirm every DTO declares every field it legitimately accepts before deploying.
+- Set `CORS_ORIGIN` to your real front-end origin in production. Do not combine `'*'` with credentials — the helper throws at boot. For a public credential-less API pass `{ cors: { origin: '*', credentials: false } }`.
+
+**2. Session secret & cookie flags — `src/main.ts`.**
+```ts
+import { buildCoreSessionOptions } from '@appxdigital/appx-core';
+// replace your inline session({ secret: … }) (drop any hardcoded fallback secret) with:
+app.use(session(buildCoreSessionOptions({
+  secret: configService.get<string>('SESSION_SECRET'),
+  cookieName: configService.get<string>('SESSION_COOKIE_NAME'),
+  ttlSeconds: configService.get<number>('SESSION_TTL') || 86400,
+  store: new CorePrismaSessionStore(prismaService, { ttl: sessionTTL }),
+})));
+```
+Ensure `SESSION_SECRET` is set (≥ 32 chars) in every environment — the app now refuses to boot without it.
+
+**3. Environment file & `NODE_ENV` — `src/app.module.ts`.**
+```ts
+import { coreEnvFilePath } from '@appxdigital/appx-core';
+// ConfigModule.forRoot({ … envFilePath: coreEnvFilePath() })
+```
+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 — 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
+```
+(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';
+import { Create<Model>Dto } from './dto/create-<model-kebab>.dto';
+import { Update<Model>Dto } from './dto/update-<model-kebab>.dto';
+
+@Post() @Permission('create')
+async create(@Body() data: Create<Model>Dto) { return super.create(data as any); }
+
+@Put(':id') @Permission('updateMany')
+async update(@Param('id') id: string, @Body() data: Update<Model>Dto) { return super.update(id, data as any); }
+```
+(Or delete an un-customized controller and re-run `appx generate` for the new template.) Add custom validation in the hand-owned `dto/*.dto.ts` subclasses — never in the `.generated.dto.ts` base. Lock sensitive columns with `/// @NoWrite` (all roles) or `restrictedFields` on the permission (per role), then regenerate. To drop a field from one endpoint's DTO, extend `OmitType(<Model>GeneratedDto, ['field'] as const)`. Full details in [`docs/dtos.md`](../docs/dtos.md).
+
+> **Nested relation writes are now an explicit, permission-gated allowlist — this is a behaviour restriction; a migrating agent MUST flag it to the developer.** Generated **create** DTOs accept only two nested operators, each authorized by ABAC: **`create`** (checked against the related model's `create` rule) and **`connect`** (checked against the related model's new dedicated **`connect`** permission — a `connect` rule is required; no rule ⇒ refused). Every other operator (`set`, `disconnect`, `update`, `upsert`, `delete`, …) is rejected (`400`). Nested writes are available on **`create` only** — `update` resolves to `updateMany`, whose payload is scalar-only. **Keep `forbidNonWhitelisted: true` on (fail loud); never `whitelist`-strip on writes.**
+>
+> **For AI agents doing this migration on an existing project:** this can break existing behaviour. Before deploying, tell the developer explicitly that (a) any nested operator other than `create`/`connect` used through CRUD will now `400`, (b) every model that is nested-`connect`ed now needs a `connect` permission or the request fails, and (c) nested writes no longer work on update endpoints. Do not proceed silently. See [`docs/dtos.md`](../docs/dtos.md#relations--nested-writes) and [`docs/permissions.md`](../docs/permissions.md).
+
+**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.
+- **`restrictedFields` under `updateMany` now applies** (it was a no-op before). Fields listed there are stripped on `PUT`. Remove any field that should remain writable.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 AppX
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 AppX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PRERELEASES.md

@@ -0,0 +1,151 @@
+# 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
+to test a change in a real project before it ships:
+
+```bash
+npm install @appxdigital/appx-core@beta            # library, latest beta
+npm install @appxdigital/appx-core@0.1.121-beta.0  # a specific library build
+npx  @appxdigital/appx-core-cli@beta create        # CLI, latest beta
+```
+
+Each prerelease gets its own entry here with fine-grained notes. When a version
+is promoted to production it is **collapsed** into a single curated section in
+[`CHANGELOG.md`](./CHANGELOG.md) with aggregated changes and consolidated
+migration steps — that public changelog is the one an upgrading project reads.
+Nothing here is a substitute for it.
+
+Prereleases are excluded from normal semver range resolution, so a project on
+`^0.1.x` never pulls one by accident — you always opt in via the `@beta` /
+`@alpha` tag or an exact version.
+
+---
+
+## [0.1.121-beta.11] — unreleased
+
+**Docs.** No code change. Documented that nested writes over HTTP CRUD are
+**one level deep** (a nested `create` DTO exposes the related model's scalars +
+`connect`, not its own relations, to avoid circular DTOs). The proxy's
+authorization is recursive; the DTO surface is the cap — deeper nesting `400`s,
+and multi-level nested writes belong in an explicit endpoint. See `docs/dtos.md`
+and `docs/limitations.md`.
+
+## [0.1.121-beta.10] — unreleased
+
+**Library.** **Nested relation writes on generated CRUD are now an explicit,
+permission-gated allowlist.** A `create` body may nest **`create`** and
+**`connect`** on its relations; both are authorized by ABAC (`create` → the
+related model's `create` rule, recursively; `connect` → the related model's new
+dedicated **`connect`** permission — a `connect` rule is required, because being
+able to *read* a record does not authorize associating it). Every other nested
+operator (`set` / `disconnect` / `update` / `upsert` / `delete` / …) is rejected
+at both the DTO layer (not emitted → `400`) and the proxy (throws). Nested
+writes are available on **`create` only** (`update` resolves to `updateMany`,
+which is scalar-only).
+
+- **Behaviour restriction — review on upgrade.** If a project used other nested
+  operators through CRUD, or connected models without a `connect` rule, those
+  requests now fail. Add `connect` rules where needed; move unsupported nested
+  writes to explicit endpoints. Keep `forbidNonWhitelisted: true` (fail loud).
+
+## [0.1.121-beta.9] — unreleased
+
+**Docs / packaging.** No code change.
+
+- Added a **`docs/` folder** (now shipped inside the npm package) — the
+  framework's source-of-truth guide: `permissions.md` (RBAC config +
+  `@Permission`/`@ExposeModels`), `data-access.md` (the Prisma proxy, ABAC
+  enforcement, single-record method contract, relations, transactions) and
+  `limitations.md` (not-ready features incl. `aggregate`/GraphQL, and caveats).
+- **Clarified the `[0.1.121]` migration in `CHANGELOG.md`.** It is now explicit
+  that regenerating the per-model DTOs and wiring them into every controller is
+  **mandatory** (it is the mass-assignment fix), and that a version bump without
+  it leaves `POST`/`PUT` endpoints accepting arbitrary fields.
+
+## [0.1.121-beta.8] — unreleased
+
+**Library.**
+
+- **Single-record data-access methods now have an honest typed contract.**
+  `prisma.model.*` re-aliases the methods that can't carry ABAC conditions, in
+  both the types and the runtime dispatch: `findUnique`→`findFirst`,
+  `findUniqueOrThrow`→`findFirstOrThrow`, `update`→`updateMany`,
+  `delete`→`deleteMany`. A mismatched call now fails at compile time instead of
+  the old runtime throw. **Breaking (types only):** `update()`/`delete()` return
+  `{ count }` and `findUnique()` takes a non-unique `where` with a nullable
+  return — adjust the call sites the compiler flags. A `*Many` permission action
+  now inherits its singular rule (`updateMany`→`update`, `deleteMany`→`delete`,
+  `createMany`→`create`), so a config can declare just `update`/`delete`/`create`.
+- **`@ExposeModels(...models)`** — expose models on a route WITHOUT a permission
+  action, for public / GUEST endpoints that must read an otherwise-restricted
+  model without adding a `GUEST` rule for it. `@Permission(action, models)` keeps
+  working unchanged. Exposed-model matching is case-insensitive.
+
+## [0.1.121-beta.7] — unreleased
+
+**Library.** `createMany` now inherits the `create` permission when not declared
+explicitly — in both the data-access proxy and the `RbacGuard`. A
+`permissions.config.ts` can declare a single `create` rule and have it cover
+`createMany` too (mirrors the existing `findMany → count/findFirst` fallback).
+One-directional: declaring only `createMany` does **not** enable `create`.
+
+- If you previously duplicated `create` and `createMany`, the `createMany` entry
+  is now redundant (harmless to keep). No action required.
+
+## [0.1.121-beta.6] — unreleased
+
+**Packaging.** The npm tarball now ships `CHANGELOG.md`, `PRERELEASES.md`, and
+`RELEASING.md` (previously only `dist/` + `README.md`). Migration steps are now
+readable from inside an installed `node_modules/@appxdigital/appx-core`, so an
+upgrading project (or an AI agent) can apply them without cloning the repo. No
+code change.
+
+## [0.1.121-beta.5] — unreleased
+
+**Library.** Field-level access control (`/// @Role(...)`) now applies to
+**nested** relation selections, not just top-level fields. Previously a query
+that selected a restricted field *through* a relation
+(`select: { relation: { select: { restrictedField: true } } }`) received that
+field; the data-access proxy now omits it at every depth, for both `select` and
+`include`, while preserving any `where` / `orderBy` you set on the relation.
+
+- Exercise reads that pull fields through relations (nested `select` / `include`,
+  including multi-level) and confirm the values you expect still come back — a
+  field annotated `@Role(<roles>)` should be absent for roles not listed.
+- No API change; regenerate is not required.
+
+## [0.1.121-beta.0] — unreleased
+
+First prerelease of the `0.1.121` hardening set. Testing target before this is
+promoted to `latest`. Full aggregated notes and migration live under
+`[0.1.121]` in `CHANGELOG.md`; the highlights to exercise in a project:
+
+- **`setupCoreSecurity(app, options?)`** — one call for the global
+  `ValidationPipe` (whitelist + `forbidNonWhitelisted`), CORS, and Helmet.
+  Verify existing DTOs still accept every field they legitimately take (the
+  whitelist rejects undeclared body properties with `400`).
+- **`buildCoreSessionOptions(...)`** — requires a session secret ≥ 32 chars and
+  sets hardened cookie flags. Confirm your env provides the secret.
+- **`coreEnvFilePath()`** — `['.env.${NODE_ENV}', '.env']`; throws if
+  `NODE_ENV` is unset. Confirm boot scripts set `NODE_ENV`.
+- **Per-model generated DTOs** — regenerate (`appx generate`) and check the
+  generated controllers compile and accept your writable fields.
+- **Create-permission enforcement in the data-access proxy** — `create` /
+  `createMany` now validate incoming data against the permission conditions and
+  default-deny when a model/role has no `create` permission. Exercise every
+  create path in the consuming app and confirm intended creates still succeed;
+  set explicit `create` permissions (or `ALL`) where needed.
+
+> How to try it: bump this package to `0.1.121-beta.0` in the project under
+> test (`npm install @appxdigital/appx-core@beta`), run the app's own suite,
+> and smoke-test create/update flows and boot. Report back before promotion.