@aaroncadillac/crudify-mongo 3.0.0 → 3.1.1

package/CHANGELOG.md

@@ -2,7 +2,32 @@
 
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/).
 
-## [2.0.0] - 2026-10-21
+## [Unreleased]
+
+### ⚠ BREAKING
+
+- **`additionalRoutes` was removed** (deprecated since the 2.x line, both the function and the array form). Passing it now throws a `TypeError` at registration pointing to the replacement. Migrate to `routes(api, ctx)` or `actions`. Because this is a breaking change on top of the published 3.0.0, the next release that includes it must be a **major** version.
+
+### Fixed
+
+- **Bulk `POST` ignored schema defaults when validating.** The array form validated each item with the static `Model.validate(data)`, which does not apply `default`s, so a bulk without a field that has a `default` (and is `required`, e.g. `status`) answered `400` while the same document sent alone worked. Each item is now built once with `new Model(data)`, validated with `doc.validate()` (defaults applied) and the same documents are passed to `Model.create(docs, { validateBeforeSave: false })` (or `insertMany`), so nothing is built or validated twice. Everything is still validated before writing (an invalid item inserts nothing), save hooks run once per document, and `createScope` checks are untouched. Release as a patch (`[patch]`).
+
+## [3.1.0] - 2026-10-22
+
+### Added
+
+- **`createScope: 'strict' | 'after-hooks'`** (default `'strict'`, exactly the 3.0.0 behaviour). With `'after-hooks'`, `beforeCreate` can derive a scope key the client does not send (for example an order's `restaurantId` from its `tableIds`): the key is no longer demanded before the hook, the **final document** is validated afterwards (`400 <field> is required` when missing, `403` when outside the scope's `{ $in }` list) and the equality keys are forced last. Bulk requests are validated entirely before anything is inserted. Invalid values throw at registration. See "Deriving a scope key" in the README.
+
+### Security
+
+- The document that reaches Mongo is always checked against the scope on create, in both modes. In `'after-hooks'` a hook can derive a key but cannot move a document out of its scope, nor overwrite a forced key.
+
+### Notes
+
+- In `'after-hooks'` mode `beforeCreate` receives the document without the forced equality keys (they are applied after the hook); in `'strict'` mode it still receives them, as in 3.0.0.
+- Publishing: the release workflow bumps the version from the commit message, so use `[minor]` for this release.
+
+## [3.0.0] - 2026-10-21
 
 Crudify is now **secure by default** and extensible. The plugin that used to hand raw client input to Mongo (and made every real application re-implement it) now sanitizes queries and bodies, bounds results, hides internals from error responses and offers `scope` / `authorize` / hooks / custom routes as first-class seams. It stays small: two files, no runtime dependencies. It does **not** authenticate or authorize by itself; it gives you the points where your tool of choice (`@fastify/auth`, Casbin, JWT...) plugs in.
 
@@ -38,7 +63,7 @@ Crudify is now **secure by default** and extensible. The plugin that used to han
 
 ### Deprecated
 
-- `additionalRoutes` (both the function form and the array form the old README described). Use `routes` or `actions`. It still works and logs a warning; it will be removed in 3.0.
+- `additionalRoutes` (both the function form and the array form the old README described). Use `routes` or `actions`. It still works and logs a warning; it will be removed in 4.0.
 
 ### Fixed
 
@@ -88,9 +113,9 @@ Each audited problem has a test; the suites live in `test/unit` (model stubbed,
 
 Needs of the first real consumer (a multi-tenant restaurant API) are covered too: tenant isolation, authorize by verb, operator allowlist, limits, writable / readonly fields, tenant forcing on create, `methods`, consistent errors, bulk, custom routes and actions with shared scope (`integration` "custom routes and actions share scope + authorize").
 
-## Migration guide: 1.x → 2.0
+## Migration guide: 1.x → 3.0
 
-| In 1.x | In 2.0 | If you need the old behaviour |
+| In 1.x | In 3.0 | If you need the old behaviour |
 |---|---|---|
 | `GET /` returned everything | 50 per page, max 100 | `query: { defaultLimit, maxLimit }`; there is no "all rows" mode, page through the results |
 | Any Mongo operator in `filters` | Allowlisted operators | `query: { operators: [...DEFAULT_OPERATORS, '$size', '$all', '$nor'] }`, or `sanitizer: false` (not recommended) |

package/README.md

@@ -75,7 +75,7 @@ Without any configuration:
 - `options` only honour `page`, `limit` and `sort`. `limit` defaults to 50 and is capped at 100; `populate`, `select`, `lean` and `pagination: false` from the client are ignored.
 - Writes drop `_id`, `__v` and the timestamps, accept no update operators besides `$set` / `$unset`, and refuse operators nested inside values.
 - Fields with `select: false` in your schema cannot be filtered or sorted on (it would be a search oracle).
-- Bulk creation goes through `Model.create`, so `pre('save')` / `post('save')` hooks always run, and an invalid item inserts nothing.
+- Bulk creation goes through `Model.create`, so `pre('save')` / `post('save')` hooks always run, schema defaults are applied before validating, and an invalid item inserts nothing.
 - Errors are mapped to a fixed shape. Duplicate keys become a generic `409`; unexpected errors become `500 Internal error` (the detail goes to your logs, never to the client).
 - Invalid ids answer `404` without touching the database.
 
@@ -138,6 +138,7 @@ The default limits (all configurable through `query`) are depth 4, 100 keys, 100
 | `routes` | none | `(api, ctx) => void`: add your own routes |
 | `actions` | none | Non-CRUD operations on one document, see below |
 | `strict` | `false` | Throw at startup if `scope` is missing or the sanitizer is disabled |
+| `createScope` | `'strict'` | When the scope's `{ $in }` keys are checked on create: `'strict'` (before `beforeCreate`) or `'after-hooks'` (on the final document), see "Deriving a scope key" |
 
 `query`: `operators`, `maxDepth`, `maxKeys`, `maxArray`, `maxBranches`, `search` (`'contains' | 'prefix' | false`), `maxSearchLength`, `filterable` (allowlist of root fields), `defaultLimit` (50), `maxLimit` (100), `maxSort`, `populate` (paths a client may populate).
 
@@ -186,6 +187,50 @@ app.register(Crudify, {
 - `scope` must return a plain object. Anything else is a `403` (fail closed). Return `{}` to say "no restriction" explicitly, or pass `scope: false`.
 - `authorize` runs first, before any query. Use it for role checks that don't depend on the document; use `scope` for anything about *which* documents (it is atomic: no read-then-check race).
 
+### Deriving a scope key in `beforeCreate` (`createScope`)
+
+Sometimes the client does not send the scope key because it is *derived*: an order carries `tableIds`, and its `restaurantId` comes from those tables. By default (`createScope: 'strict'`, the behaviour of 3.0.0) Crudify demands the `{ $in }` key **before** `beforeCreate` runs, so such a resource answers `400 restaurantId is required`.
+
+With `createScope: 'after-hooks'` the create pipeline becomes:
+
+1. sanitize the client document (scope keys the client sent are kept, forced equality keys are dropped);
+2. run `beforeCreate(data, req)`, which can derive or stamp the key;
+3. **validate the final document**: every `{ $in }` key must exist (`400 <field> is required`) and be in the list (`403 Forbidden`);
+4. impose the equality keys last, so the hook cannot overwrite them.
+
+```js
+app.register(Crudify, {
+  url: '/orders',
+  Model: Order,
+  createScope: 'after-hooks',
+  scope: async (req) => ({
+    accountId: req.user.accountId,
+    restaurantId: { $in: await allowedRestaurantIds(req.user) } // e.g. from your permission system
+  }),
+  hooks: {
+    // `data` has no accountId yet: it is forced after this hook
+    beforeCreate: async (data) => {
+      const tables = await Table.find({ _id: { $in: data.tableIds ?? [] } }).lean()
+      const restaurants = new Set(tables.map(t => String(t.restaurantId)))
+      if (tables.length !== data.tableIds?.length || restaurants.size !== 1) {
+        throw new CrudifyError(400, 'tableIds must belong to a single restaurant')
+      }
+      return { ...data, restaurantId: [...restaurants][0] }
+    }
+  }
+})
+```
+
+What stays guaranteed: a hook can derive the key but **never move a document out of its scope**, because Crudify checks the result and forces the equality keys itself. Bulk requests are validated entirely before anything is written. `list`, `get`, `update` and `delete` are not affected.
+
+What you take on by choosing it:
+
+- `beforeCreate` receives the document **without the forced keys** (`accountId` above is not there yet). Don't rely on them inside the hook.
+- The hook must derive the key from trusted data (look it up in your database; never copy it from another client-supplied field without checking).
+- A hook that derives nothing is a `400`, and one that derives a value outside the caller's list is a `403`.
+
+Not recommended: setting `scope: {}` for the action and validating the tenant yourself inside `beforeCreate`. It works, but then nothing is checked by Crudify and a forgotten check is a cross-tenant leak; that risk is entirely yours.
+
 ## Hooks and request order
 
 ```js
@@ -252,7 +297,7 @@ app.register(Crudify, {
 
 `ctx` has `Model`, `url`, `scope(req, action)`, `where(req, action, base)` (a filter with the scope applied), `load(req, action, id)` (a real Mongoose document, or 404), `list(req)` (sanitized + scoped paginate), `sanitize.{filter, options, update, create, query}`, `serialize`, `notFound` and `checkId`.
 
-> `additionalRoutes` (a function, or an array of `{ method, url, handler }`) still works but is deprecated and will be removed in 3.0. Use `routes` or `actions`.
+> `additionalRoutes` (deprecated in 2.x) was removed: passing it throws at registration. Use `routes` or `actions`.
 
 ## Recipes
 

package/crudify.js

@@ -124,6 +124,9 @@ const normalizeOptions = (opts, log) => {
   const unknown = methods.find(m => !VERBS.includes(m))
   if (unknown) throw new TypeError(`Crudify: unknown method "${unknown}"`)
   if (methods.includes('list') && typeof Model.paginate !== 'function') throw new TypeError('Crudify: `list` needs mongoose-paginate-v2 (Model.paginate)')
+  if (opts.additionalRoutes !== undefined) throw new TypeError('Crudify: `additionalRoutes` was removed, use `routes(api, ctx)` or `actions`')
+  const createScope = opts.createScope === undefined ? 'strict' : opts.createScope
+  if (createScope !== 'strict' && createScope !== 'after-hooks') throw new TypeError('Crudify: `createScope` must be "strict" or "after-hooks"')
   const hooks = opts.hooks ?? {}
   for (const [name, fn] of Object.entries({ scope, authorize, serialize, mapError, ...hooks })) {
     if (fn !== undefined && fn !== false && typeof fn !== 'function') throw new TypeError(`Crudify: \`${name}\` must be a function`)
@@ -147,9 +150,9 @@ const normalizeOptions = (opts, log) => {
     : { ...compiled, ...(isPlainObject(opts.sanitizer) && opts.sanitizer) }
 
   return {
-    url, Model, methods, scope, authorize, serialize, mapError, hooks, bulk, san,
+    url, Model, methods, scope, authorize, serialize, mapError, hooks, bulk, san, lateScope: createScope === 'after-hooks',
     lean: !!opts.lean, select: opts.select, routeOptions: opts.routeOptions ?? {}, handlers: opts.handlers ?? {},
-    routes: opts.routes, actions: opts.actions ?? {}, additionalRoutes: opts.additionalRoutes,
+    routes: opts.routes, actions: opts.actions ?? {},
     idIsObjectId: Model.schema.path('_id')?.instance === 'ObjectId',
     schemas: buildSchemas({ JSONSchema: opts.JSONSchema, readonly: new Set(readonly), schema: opts.schema, bulk })
   }
@@ -193,15 +196,25 @@ const createHandlers = (c, ctx) => {
   const { Model, hooks } = c
   const { serialize } = ctx
 
-  const prepare = (item, rules) => {
-    const data = ctx.sanitize.create(item, rules.keys)
-    for (const field in rules.inLists) {
-      const v = item[field]
+  // Scope keys of a new document: `{ $in: [...] }` values must contain the document's own, equality values are forced.
+  const checkLists = (data, lists) => {
+    for (const field in lists) {
+      const v = data[field]
       if (v === undefined) throw new CrudifyError(400, `${field} is required`, { code: 'validation_error' })
-      if (!rules.inLists[field].some(x => String(x) === String(v))) throw forbidden()
-      data[field] = v
+      if (!lists[field].some(x => String(x) === String(v))) throw forbidden()
     }
-    return Object.assign(data, rules.forced)
+  }
+
+  // 'strict' checks the client's document before `beforeCreate`; 'after-hooks' lets the hook derive the keys and checks
+  // the FINAL document instead, forcing the equality keys last so a hook can never move a document out of its scope.
+  const prepare = async (item, req, rules) => {
+    const data = ctx.sanitize.create(item, rules.keys)
+    for (const field in rules.inLists) if (item[field] !== undefined) data[field] = item[field]
+    if (!c.lateScope) { checkLists(data, rules.inLists); Object.assign(data, rules.forced) }
+    const out = hooks.beforeCreate ? (await hooks.beforeCreate(data, req)) ?? data : data
+    if (!c.lateScope) return out
+    checkLists(out, rules.inLists)
+    return Object.assign(out, rules.forced)
   }
 
   return {
@@ -218,14 +231,12 @@ const createHandlers = (c, ctx) => {
       const rules = writeRules(req.crudify.filter)
       const isBulk = Array.isArray(req.body)
       const data = []
-      for (const item of isBulk ? req.body : [req.body]) {
-        const d = prepare(item, rules)
-        data.push(hooks.beforeCreate ? (await hooks.beforeCreate(d, req)) ?? d : d)
-      }
+      for (const item of isBulk ? req.body : [req.body]) data.push(await prepare(item, req, rules))
       let docs
-      if (isBulk) { // validate everything first: an invalid item inserts nothing
-        await Promise.all(data.map(d => Model.validate(d)))
-        docs = await (c.bulk.insertMany ? Model.insertMany(data) : Model.create(data)) // create() runs save hooks
+      if (isBulk) { // build each document once (applies schema defaults) and validate all before writing: an invalid item inserts nothing
+        const built = data.map(d => new Model(d))
+        await Promise.all(built.map(d => d.validate()))
+        docs = await (c.bulk.insertMany ? Model.insertMany(built) : Model.create(built, { validateBeforeSave: false })) // create() runs save hooks; already validated
       } else docs = await Model.create(data[0])
       if (hooks.afterCreate) await hooks.afterCreate(docs, req)
       reply.code(201)
@@ -261,8 +272,6 @@ const createHandlers = (c, ctx) => {
 }
 
 // ── The plugin ───────────────────────────────────────────────────────────────
-let deprecationShown = false
-
 async function Crudify (fastify, opts) {
   const c = normalizeOptions(opts, fastify.log)
   const ctx = createContext(c)
@@ -322,11 +331,6 @@ async function Crudify (fastify, opts) {
     route(method.toUpperCase(), path, { ...rest, action, load }, handler)
   }
 
-  if (c.additionalRoutes) { // deprecated, removed in 3.0
-    if (!deprecationShown) { deprecationShown = true; fastify.log.warn('Crudify: `additionalRoutes` is deprecated, use `routes` or `actions`') }
-    if (typeof c.additionalRoutes === 'function') c.additionalRoutes(fastify, opts)
-    else for (const { method = 'GET', url, handler, ...rest } of c.additionalRoutes) route(method.toUpperCase(), url, rest, handler)
-  }
 }
 
 Crudify[Symbol.for('plugin-meta')] = { name: 'crudify-mongo', fastify: '4.x || 5.x' }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaroncadillac/crudify-mongo",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": "A secure-by-default CRUD generator for Fastify and Mongoose, with hooks, scoping and a built-in query sanitizer",
   "keywords": [
     "fastify",