@appxdigital/appx-core 0.1.121-beta.5 → 0.1.121-beta.7

package/CHANGELOG.md

@@ -0,0 +1,104 @@
+# 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.
+
+### 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
+
+> 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.
+
+**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.**
+```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):
+```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.
+
+**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/PRERELEASES.md

@@ -0,0 +1,83 @@
+# Prerelease log
+
+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.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.

package/RELEASING.md

@@ -0,0 +1,168 @@
+# Releasing
+
+This repo publishes **two independent packages**, each versioned on its own:
+
+- **`@appxdigital/appx-core`** — the runtime library (root `package.json`),
+  released via **`v*`** tags (`release.yml`).
+- **`@appxdigital/appx-core-cli`** — the `appx-core` CLI (`cli/package.json`),
+  released via **`cli-v*`** tags (`release-cli.yml`).
+
+Both follow the same posture: publishing is deliberate — **it only happens when
+you push a git tag** — and production (`latest`) pauses for a human approval
+before it goes live.
+
+## Channels
+
+Library (`v*` tags):
+
+| You push tag       | npm dist-tag | Consumers install with            | Gated?          |
+| ------------------ | ------------ | --------------------------------- | --------------- |
+| `v1.2.3-alpha.N`   | `alpha`      | `…/appx-core@alpha`               | no              |
+| `v1.2.3-beta.N`    | `beta`       | `…/appx-core@beta`                | no              |
+| `v1.2.3-rc.N`      | `next`       | `…/appx-core@next`                | no              |
+| `v1.2.3`           | `latest`     | `…/appx-core` (default)           | **yes** — approval |
+
+CLI (`cli-v*` tags) — identical channels for `@appxdigital/appx-core-cli`:
+
+| You push tag         | npm dist-tag | Consumers install with          | Gated?          |
+| -------------------- | ------------ | ------------------------------- | --------------- |
+| `cli-v1.2.3-beta.N`  | `beta`       | `…/appx-core-cli@beta`          | no              |
+| `cli-v1.2.3`         | `latest`     | `…/appx-core-cli` (default)     | **yes** — approval |
+
+Prereleases are excluded from `^1.2.x` range resolution, so a project on a caret
+range never pulls one by accident — testers opt in via the tag or an exact
+version. Merging to `main` **never** publishes; it only runs CI (library build +
+tests on mysql and postgres, plus a CLI smoke check).
+
+## Two files, two audiences
+
+- **`PRERELEASES.md`** — granular, one entry per alpha/beta build. What a tester
+  reads.
+- **`CHANGELOG.md`** — collapsed, one section per production release with
+  aggregated changes and consolidated migration steps. What an upgrading project
+  reads. When you promote a version, distil its prerelease entries into a single
+  `CHANGELOG.md` section.
+
+## One-time setup (before the first publish)
+
+1. **npm Trusted Publisher (OIDC) — one per package.** On npmjs.com → the
+   package → *Settings* → *Trusted Publisher* → GitHub Actions. Add **two**,
+   both owner `appxdigital`, repo `appx-core`:
+   - `@appxdigital/appx-core` → workflow `release.yml`
+   - `@appxdigital/appx-core-cli` → workflow `release-cli.yml`
+
+   This lets CI mint a short-lived publish token per run — **no `NPM_TOKEN`
+   secret is stored anywhere**, and every publish carries supply-chain
+   provenance.
+
+2. **GitHub `production` environment (the approval gate).** Repo → *Settings* →
+   *Environments* → *New environment* → name it exactly `production` → enable
+   *Required reviewers* and add yourself (and/or the team). The
+   `publish-production` job targets this environment, so a clean tag will wait
+   for a click before publishing to `latest`.
+
+## Cutting a release
+
+The tag must match `package.json`'s version exactly, or the release job fails
+fast (a guard against mistagging). Convenience scripts keep them in lockstep and
+create the tag for you — they **do not push**, so pushing stays a deliberate
+step:
+
+There are two per package — a **test build** and a **production release**:
+
+| Script                          | What it does                          | Tag             | Goes to           |
+| ------------------------------- | ------------------------------------- | --------------- | ----------------- |
+| `npm run release:beta`          | library test build (`…-beta.N`)       | `v…-beta.N`     | `beta` channel    |
+| `npm run release:production`    | promote library to everyone           | `vX.Y.Z`        | `latest` (gated)  |
+| `npm run release:cli:beta`      | CLI test build (`…-beta.N`)           | `cli-v…-beta.N` | `beta` channel    |
+| `npm run release:cli:production`| promote CLI to everyone               | `cli-vX.Y.Z`    | `latest` (gated)  |
+
+`release:beta` publishes only to people who opt in with `@beta`; `release:production`
+is what everyone gets by default, and it pauses for your approval before going
+live. Each command bumps the version, commits, and creates the tag, then prints
+the exact `git push origin HEAD --follow-tags` for you to run when ready — they
+never push on their own.
+
+Rarer cases go through the underlying script directly:
+`node scripts/release.mjs lib alpha` (alpha channel), `… lib minor` (a feature
+bump), or `… lib X.Y.Z-beta.0` (an explicit version — e.g. the first beta of a
+version already sitting in `package.json`).
+
+The manual steps below show what those scripts do under the hood.
+
+### Beta (test in projects first)
+
+```bash
+# set the version + create the matching tag + commit, without auto-pushing
+npm version 0.1.121-beta.0 --message "release: %s"
+git push origin main --follow-tags
+```
+
+The `Release` workflow builds, tests, and publishes to the `beta` dist-tag.
+Then, in a project you want to test against:
+
+```bash
+npm install @appxdigital/appx-core@beta
+```
+
+Iterate with `npm version prerelease --preid beta` (→ `-beta.1`, `-beta.2`, …),
+each push publishing a new granular `PRERELEASES.md` entry.
+
+### Promote to production (`latest`)
+
+When the beta is validated in real projects:
+
+```bash
+# drop the prerelease suffix -> clean version
+npm version 0.1.121 --message "release: %s"
+git push origin main --follow-tags
+```
+
+The workflow builds and tests, then **pauses** on the `production` environment.
+Approve it in the repo's *Actions* tab → the running release → *Review
+deployments* → *Approve and deploy*. It then publishes to `latest`.
+
+> Alternatively, promotion can be a pure retag without republishing:
+> `npm dist-tag add @appxdigital/appx-core@0.1.121-beta.N latest`. The
+> tag-driven workflow above is preferred because it re-runs tests and records
+> provenance for the exact `latest` artifact.
+
+### Alpha (rough, one or two projects)
+
+```bash
+npm version 0.1.122-alpha.0 --message "release: %s"
+git push origin main --follow-tags
+# in the project:  npm install @appxdigital/appx-core@alpha
+```
+
+### CLI (`@appxdigital/appx-core-cli`)
+
+Same flow, but bump `cli/package.json` and use the `cli-v` tag prefix. The tag
+must match `cli/package.json`'s version.
+
+```bash
+# beta:
+npm --prefix cli version 1.0.21-beta.0 --message "release cli: %s"
+git commit -am "release cli: 1.0.21-beta.0"   # npm version --prefix does not commit
+git tag cli-v1.0.21-beta.0
+git push origin main --follow-tags
+#   test:  npx @appxdigital/appx-core-cli@beta create …
+
+# production (gated — approve in the Actions tab):
+npm --prefix cli version 1.0.21 --message "release cli: %s"
+git commit -am "release cli: 1.0.21"
+git tag cli-v1.0.21
+git push origin main --follow-tags
+```
+
+> `npm version --prefix cli` bumps `cli/package.json` but does not create the
+> git commit/tag (that only happens when run in the repo root). Commit and tag
+> explicitly with the `cli-v` prefix as shown.
+
+## Manual fallback
+
+If CI is unavailable, you can still publish by hand: `rimraf dist && npm run
+build && npm publish --tag <dist-tag> --access public` for the library, and
+`cd cli && npm publish --tag <dist-tag> --access public` for the CLI. This
+bypasses the tests, the approval gate, and provenance, so prefer the tag-driven
+flow.

package/dist/common/guards/rbac.guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rbac.guard.d.ts","sourceRoot":"","sources":["../../../src/common/guards/rbac.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,WAAW,EACX,gBAAgB,EAInB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAC,qBAAqB,EAAkB,MAAM,kCAAkC,CAAC;AAExF,qBACa,SAAU,YAAW,WAAW;IAErC,OAAO,CAAC,SAAS;IACiB,OAAO,CAAC,iBAAiB;gBADnD,SAAS,EAAE,SAAS,EACc,iBAAiB,EAAE,qBAAqB;IAGhF,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;CAoCjE"}
+{"version":3,"file":"rbac.guard.d.ts","sourceRoot":"","sources":["../../../src/common/guards/rbac.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,WAAW,EACX,gBAAgB,EAInB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAC,qBAAqB,EAAkB,MAAM,kCAAkC,CAAC;AAExF,qBACa,SAAU,YAAW,WAAW;IAErC,OAAO,CAAC,SAAS;IACiB,OAAO,CAAC,iBAAiB;gBADnD,SAAS,EAAE,SAAS,EACc,iBAAiB,EAAE,qBAAqB;IAGhF,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;CA0CjE"}

package/dist/common/guards/rbac.guard.js

@@ -38,7 +38,13 @@ let RbacGuard = exports.RbacGuard = class RbacGuard {
         if (!rolePermissions) {
             throw new common_1.ForbiddenException(`No permissions defined for role ${user.role} on model ${model}`);
         }
-        const permission = rolePermissions[action];
+        // `createMany` inherits the `create` rule when not defined explicitly —
+        // mirrors the data-access proxy, which validates each batched row against
+        // the `create` permission. Lets a config declare just `create`.
+        let permission = rolePermissions[action];
+        if (!permission && action === 'createMany') {
+            permission = rolePermissions['create'];
+        }
         if (!permission) {
             throw new common_1.ForbiddenException(`Action ${action} not allowed for role ${user.role} on model ${model}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@appxdigital/appx-core",
-    "version": "0.1.121-beta.5",
+    "version": "0.1.121-beta.7",
     "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",
@@ -99,7 +99,10 @@
         "rxjs": "~7.8.1"
     },
     "files": [
-        "dist"
+        "dist",
+        "CHANGELOG.md",
+        "PRERELEASES.md",
+        "RELEASING.md"
     ],
     "engines": {
         "npm": ">=10.0.0",