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

package/README.md

@@ -4,6 +4,10 @@
   <img src="./public/appx-core-logo.png" alt="AppX Core Logo" width="220" />
 </p>
 
+[![CI](https://github.com/appxdigital/appx-core/actions/workflows/ci.yml/badge.svg)](https://github.com/appxdigital/appx-core/actions/workflows/ci.yml)
+[![Release](https://github.com/appxdigital/appx-core/actions/workflows/release.yml/badge.svg)](https://github.com/appxdigital/appx-core/actions/workflows/release.yml)
+[![Release CLI](https://github.com/appxdigital/appx-core/actions/workflows/release-cli.yml/badge.svg)](https://github.com/appxdigital/appx-core/actions/workflows/release-cli.yml)
+
 **AppX Core** is a production-oriented backend foundation that accelerates the delivery of secure, data-access-controlled APIs with an integrated admin backoffice. It scaffolds a native **NestJS** application and extends it with opinionated building blocks for authentication, authorization (ABAC-first), CRUD acceleration, and administration through **AdminJS**.
 
 Built and maintained by **AppX** (appx-digital.com).
@@ -33,6 +37,7 @@ Built and maintained by **AppX** (appx-digital.com).
 - [Permissions](#permissions)
   - [Permissions Configuration Shape](#permissions-configuration-shape)
   - [Rules](#rules)
+  - [Reading Related Models](#reading-related-models)
   - [Action Aliases and Fallbacks](#action-aliases-and-fallbacks)
   - [Custom Controller Actions](#custom-controller-actions)
   - [Temporarily Exposing Models](#temporarily-exposing-models)
@@ -110,6 +115,21 @@ AppX Core is designed as a **base layer** on top of NestJS:
 npm install -g @appxdigital/appx-core-cli
 ```
 
+**Release channels.** AppX Core publishes both packages on two npm dist-tags:
+
+- **`latest`** — stable releases. This is what the commands above install.
+- **`beta`** — prereleases, for trying upcoming changes before they're promoted. Opt in explicitly with the `@beta` tag (a caret range such as `^0.1.x` never resolves to a prerelease on its own):
+
+```bash
+npm install -g @appxdigital/appx-core-cli@beta   # CLI prerelease
+```
+
+`appx-core create` scaffolds a project that depends on the **stable** library. To test a library prerelease in that project, install it there:
+
+```bash
+npm install @appxdigital/appx-core@beta          # inside your project
+```
+
 ### 2) Create a New Project
 
 ```bash
@@ -119,10 +139,13 @@ cd <your-project>
 
 ### 3) Configure Environment
 
-Create a `.env` file at the project root:
+`appx-core create` **already writes a `.env`** at the project root, with secure
+random secrets generated for you. You don't need to create it by hand — just
+open it and set your database connection (and `CORS_ORIGIN` for production). The
+generated file looks like this:
 
 ```bash
-## DataBase Configurations ##
+## Database ##
 DB_HOST=127.0.0.1
 DB_PORT=3306
 DB_USER=root
@@ -131,22 +154,36 @@ DB_NAME=generic
 DB_PROVIDER=mysql
 DB_URL="${DB_PROVIDER}://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}"
 
-## Project configurations ##
+## App ##
 APP_PORT=3000
 USE_TRANSACTION=true
+CORS_ORIGIN=http://localhost:3000   # your front-end origin; set to your real domain in production
 
 ## Sessions ##
-SESSION_SECRET="change-me"
-SESSION_COOKIE_NAME="session_nestjs-project"
+SESSION_SECRET=<64-char random hex — generated for you>
+SESSION_COOKIE_NAME=session_nestjs-project
 SESSION_TTL=86400
 
 ## JWT ##
 JWT_EXPIRES_IN=10d
 JWT_REFRESH_EXPIRES_IN=1y
-JWT_SECRET="change-me"
-JWT_REFRESH_SECRET="change-me"
+JWT_SECRET=<random — generated for you>
+JWT_REFRESH_SECRET=<random — generated for you>
 ```
 
+> **Keep the generated secrets — don't replace them with placeholders like `change-me`.**
+> `SESSION_SECRET` must be **at least 32 characters** or the app throws at
+> startup (`buildCoreSessionOptions` — there is no insecure fallback).
+>
+> **`NODE_ENV`** must be set in the runtime environment. The `start` scripts set
+> it to `development`; set it explicitly in production. Env files resolve as
+> `.env.${NODE_ENV}` first, then `.env` (via `coreEnvFilePath()`), so a plain
+> `.env` works for development and you can add `.env.production` for prod.
+
+Baseline HTTP hardening (a whitelisting `ValidationPipe`, CORS, and Helmet) is
+applied for you by `setupCoreSecurity(app, …)` in `src/main.ts`; `helmet` is a
+peer dependency the scaffold already includes.
+
 ### 4) Define Data Models
 
 Edit:
@@ -288,6 +325,32 @@ deleteMany: {
 },
 ```
 
+### Reading Related Models
+
+When a query pulls in a relation (`include: { author: true }`, or the equivalent `select`), that related model's **own** read permissions are enforced too — a relation is never a way around ABAC. How this plays out depends on the relation's cardinality.
+
+**To-one relations (`belongsTo`, 1:1)** are filtered with *inner-join* semantics: the related model's read `conditions` are applied to the **parent** row.
+
+- If the related model has **no** read rule for the caller's role, including the relation raises a `403` (`Missing permissions on model X`). Grant a read rule on every model you expose through an `include`.
+- If the related model has a **conditional** read rule and the specific related row does not satisfy it, the **whole parent row is dropped** from the result (`findFirst` returns `null`; `findMany` omits it) — the parent is *not* returned with the relation set to `null`. Put plainly: you cannot see a row whose related record you are not allowed to see.
+
+**To-many relations (`hasMany`, many-to-many)** are filtered in place: the parent row is kept and the child list is narrowed to the rows the caller may read (which can be empty).
+
+Example — `Comment.author` points at `User`, and a `User` is only self-readable:
+
+```ts
+User: {
+  USER: { findMany: { conditions: { id: PermissionPlaceholder.USER_ID } } },
+},
+Comment: {
+  USER: { findMany: { conditions: { authorId: PermissionPlaceholder.USER_ID } } },
+},
+```
+
+`comment.findFirst({ where: { id }, include: { author: true } })` returns the comment only when the caller is also its author (a `User` row they are allowed to read); otherwise the comment itself is filtered out. This is intentional and fails closed.
+
+> **Why not return the parent with the relation nulled?** Prisma does not allow a `where` filter on a to-one relation inside `include` / `select`, so the condition is applied to the parent instead. Masking the relation while keeping the parent would require an extra query per included relation; the framework favors the single-query, fail-closed behavior.
+
 ### Action Aliases and Fallbacks
 
 To avoid duplicated config, the permissions engine supports fallback behavior. In practice:

package/dist/prisma/prisma.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prisma.service.d.ts","sourceRoot":"","sources":["../../src/prisma/prisma.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"prisma.service.d.ts","sourceRoot":"","sources":["../../src/prisma/prisma.service.ts"],"names":[],"mappings":"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"}

package/dist/prisma/prisma.service.js

@@ -226,6 +226,37 @@ let PrismaService = exports.PrismaService = PrismaService_1 = class PrismaServic
             omitFields.forEach((field) => {
                 delete args.select[field];
             });
+            // Omission must also apply to nested relation selections. Without this,
+            // a caller reads an omitted field on a RELATED model by nesting the
+            // request (e.g. `select: { rel: { select: { secret: true } } }`) — the
+            // top-level delete above only covers this model's own fields.
+            for (const key of Object.keys(args.select)) {
+                const relation = this.getRelation(modelName, key);
+                if (!relation) {
+                    continue; // scalar field (`true`) or `_count` — nothing to recurse
+                }
+                const relatedOmit = this.getFieldsToOmit(relation.model, userRole);
+                const value = args.select[key];
+                if (value === true) {
+                    // `rel: true` returns every scalar of the related model — narrow
+                    // it to the readable ones.
+                    args.select[key] = {
+                        select: this.buildSelectFields(relation.model, relatedOmit, null, null, userRole),
+                    };
+                }
+                else if (value && typeof value === 'object') {
+                    if (value.select || value.include) {
+                        // Recurse — strips the related model's omitted fields (and
+                        // deeper) while preserving any where/orderBy/take on `value`.
+                        args.select[key] = this.applyFieldOmission(relation.model, userRole, value);
+                    }
+                    else {
+                        // Relation args with no explicit projection (e.g. `{ where }`)
+                        // — inject a select that excludes omitted fields.
+                        value.select = this.buildSelectFields(relation.model, relatedOmit, null, null, userRole);
+                    }
+                }
+            }
         }
         else if (args.include) {
             this.debug(`Found included model '${modelName}', generating select fields`);

package/package.json

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