@bedrockio/model 0.2.21 → 0.3.0

package/README.md

@@ -472,7 +472,7 @@ In the above example `getCreateValidation` returns a
 `validateBody` middleware. The `password` field is an additional field that is
 appended to the create schema.
 
-There are 3 main methods to generate schemas:
+There are 4 main methods to generate schemas:
 
 - `getCreateValidation`: Validates all fields while disallowing reserved fields
   like `id`, `createdAt`, and `updatedAt`.
@@ -488,6 +488,7 @@ There are 3 main methods to generate schemas:
     allowed.
   - Array fields are "unwound". This means that for example given an array field
     `categories`, input may be either a string or an array of strings.
+- `getDeleteValidation`: Only used for access validation (more below).
 
 #### Named Validations
 
@@ -752,8 +753,7 @@ queries and more unneeded data transfer over the wire.
 
 For this reason calling `populate` manually is highly preferable, however in
 complex situations this can easily be a lot of overhead. The include module
-attempts to greatly streamline this process by adding an `include` method to
-queries:
+attempts to streamline this process by adding an `include` method to queries:
 
 ```js
 const product = await Product.findById(id).include([
@@ -905,18 +905,48 @@ The `getSearchValidation` will allow the `include` property to be passed,
 letting the client populate documents as they require. Note that the fields a
 client is able to include is subject to [access control](#access-control).
 
+#### Other Differences with Populate
+
+Calling `populate` on a Mongoose document will always load the current data. In
+contrast, `include` will only load when not yet populated, providing better
+performance for most situations such as pre save hooks:
+
+```js
+schema.pre('save', async () => {
+  // Will not result in a populate call if the
+  // owner document has already been populated.
+  await this.include('owner');
+
+  this.ownerName = this.owner.name;
+});
+```
+
+If always fetching the current document is preferred, the `force` option can be
+passed:
+
+```js
+await shop.include('owner', {
+  force: true,
+});
+```
+
 ### Access Control
 
 This package applies two forms of access control:
 
-#### Read Access
+- [Field Access](#field-access)
+- [Document Access](#document-access)
+
+#### Field Access:
+
+##### Read Access
 
 Read access influences how documents are serialized. Fields that have been
 denied access will be stripped out. Additionally it will influence the
 validation schema for `getSearchValidation`. Fields that have been denied access
 are not allowed to be searched on and will throw an error.
 
-#### Write Access
+##### Write Access
 
 Write access influences validation in `getCreateValidation` and
 `getUpdateValidation`. Fields that have been denied access will throw an error
@@ -924,7 +954,7 @@ unless they are identical to what is already set on the document. Note that in
 the case of `getCreateValidation` no document has been created yet so a denied
 field will always result in an error if passed.
 
-#### Defining Access
+##### Defining Field Access
 
 Access is defined in schemas with the `readAccess` and `writeAccess` options:
 
@@ -1098,7 +1128,7 @@ owner, as this example illustrates:
 }
 ```
 
-#### Notes on Read Access
+##### Notes on Read Access
 
 Note that all forms of read access require that `.toObject` is called on the
 document with special parameters, however this method is called on internal
@@ -1107,11 +1137,54 @@ this reason it will never fail even if it cannot perform the correct access
 checks. Instead any fields with `readAccess` defined on them will be stripped
 out.
 
-#### Notes on Write Access
+##### Notes on Write Access
 
 Note that `self` is generally only meaningful on a User model as it will always
 check the document is the same as `authUser`.
 
+#### Document Access
+
+In addition to the fine grained control of accessing fields, documents
+themselves may also have access control. This can be defined in the `access` key
+of the model definition:
+
+```jsonc
+// user.json
+{
+  "attributes": {
+    // ...
+  },
+  "access": {
+    // A user may update themselves or an admin.
+    "update": ["self", "admin"],
+    // Only an admin may delete a user.
+    "delete": ["admin"]
+  }
+}
+```
+
+The same options can be used as
+[document based access on fields](#document-based-access), so this could be
+`owner`, etc:
+
+```jsonc
+// shop.json
+{
+  "attributes": {
+    "owner": {
+      "type": "ObjectId",
+      "ref": "User"
+    }
+  },
+  "access": {
+    // An owner may update their own shop.
+    "update": ["owner", "admin"],
+    // Only an admin may delete a shop.
+    "delete": ["admin"]
+  }
+}
+```
+
 ### Delete Hooks
 
 Delete hooks are a powerful way to define what actions are taken on document

package/dist/cjs/access.js

@@ -4,22 +4,13 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.hasAccess = hasAccess;
-exports.hasReadAccess = hasReadAccess;
-exports.hasWriteAccess = hasWriteAccess;
 var _errors = require("./errors");
 var _warn = _interopRequireDefault(require("./warn"));
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-function hasReadAccess(allowed, options) {
-  return hasAccess('read', allowed, options);
-}
-function hasWriteAccess(allowed, options) {
-  return hasAccess('write', allowed, options);
-}
-
 /**
  * @param {string|string[]} allowed
  */
-function hasAccess(type, allowed = 'all', options = {}) {
+function hasAccess(allowed = 'all', options = {}) {
   if (allowed === 'all') {
     return true;
   } else if (allowed === 'none') {

package/dist/cjs/include.js

@@ -6,7 +6,8 @@ Object.defineProperty(exports, "__esModule", {
 exports.INCLUDE_FIELD_SCHEMA = void 0;
 exports.applyInclude = applyInclude;
 exports.checkSelects = checkSelects;
-exports.getIncludes = getIncludes;
+exports.getDocumentParams = getDocumentParams;
+exports.getParams = getParams;
 var _mongoose = _interopRequireDefault(require("mongoose"));
 var _lodash = require("lodash");
 var _yada = _interopRequireDefault(require("@bedrockio/yada"));
@@ -36,7 +37,7 @@ function applyInclude(schema) {
       const {
         select,
         populate
-      } = getQueryIncludes(this, filter.include);
+      } = getQueryParams(this, filter.include);
       this.select(select);
       this.populate(populate);
       delete filter.include;
@@ -78,7 +79,7 @@ function applyInclude(schema) {
       const {
         select,
         populate
-      } = getDocumentIncludes(this, include);
+      } = getDocumentParams(this, include);
       this.$locals.select = select;
       this.$locals.populate = populate;
     }
@@ -98,12 +99,12 @@ function applyInclude(schema) {
   // Perform population immediately when instance method is called.
   // Store selects as a local variable which will be checked
   // during serialization.
-  schema.method('include', async function include(include) {
+  schema.method('include', async function include(include, options) {
     if (include) {
       const {
         select,
         populate
-      } = getDocumentIncludes(this, include);
+      } = getDocumentParams(this, include, options);
       this.$locals.select = select;
       await this.populate(populate);
     }
@@ -147,16 +148,34 @@ function checkSelects(doc, ret) {
 }
 
 // Exported for testing.
-function getIncludes(modelName, arg) {
+function getParams(modelName, arg) {
   const paths = Array.isArray(arg) ? arg : [arg];
   const node = pathsToNode(paths, modelName);
   return nodeToPopulates(node);
 }
-function getQueryIncludes(query, arg) {
-  return getIncludes(query.model.modelName, arg);
+
+// Exported for testing.
+function getDocumentParams(doc, arg, options = {}) {
+  const params = getParams(doc.constructor.modelName, arg);
+  if (!options.force) {
+    params.populate = params.populate.filter(p => {
+      return !isDocumentPopulated(doc, p);
+    });
+  }
+  return params;
+}
+function isDocumentPopulated(doc, params) {
+  if (doc.populated(params.path)) {
+    const sub = doc.get(params.path);
+    return params.populate.every(p => {
+      return isDocumentPopulated(sub, p);
+    });
+  } else {
+    return false;
+  }
 }
-function getDocumentIncludes(doc, arg) {
-  return getIncludes(doc.constructor.modelName, arg);
+function getQueryParams(query, arg) {
+  return getParams(query.model.modelName, arg);
 }
 
 // Note that:

package/dist/cjs/serialization.js

@@ -6,8 +6,8 @@ Object.defineProperty(exports, "__esModule", {
 exports.serializeOptions = void 0;
 var _lodash = require("lodash");
 var _include = require("./include");
-var _access = require("./access");
 var _utils = require("./utils");
+var _access = require("./access");
 const DISALLOWED_FIELDS = ['deleted', 'deletedRefs'];
 const serializeOptions = exports.serializeOptions = {
   getters: true,
@@ -63,7 +63,7 @@ function isAllowedField(key, field, options) {
       readAccess
     } = (0, _utils.getField)(field, key);
     try {
-      return (0, _access.hasReadAccess)(readAccess, options);
+      return (0, _access.hasAccess)(readAccess, options);
     } catch {
       return false;
     }

package/dist/cjs/validation.js

@@ -112,6 +112,7 @@ function applyValidation(schema, definition) {
       stripTimestamps: true,
       allowExpandedRefs: true,
       requireWriteAccess: true,
+      updateAccess: definition.access?.update,
       ...(hasUnique && {
         assertUniqueOptions: {
           schema,
@@ -120,6 +121,13 @@ function applyValidation(schema, definition) {
       })
     });
   });
+  schema.static('getDeleteValidation', function getDeleteValidation() {
+    const allowed = definition.access?.delete || 'all';
+    return validateAccess('delete', _yada.default, allowed, {
+      model: this,
+      message: 'You do not have permissions to delete this document.'
+    });
+  });
   schema.static('getSearchValidation', function getSearchValidation(options = {}) {
     const {
       defaults,
@@ -180,7 +188,8 @@ function getValidationSchema(attributes, options = {}) {
   const {
     appendSchema,
     assertUniqueOptions,
-    allowInclude
+    allowInclude,
+    updateAccess
   } = options;
   let schema = getObjectSchema(attributes, options);
   if (assertUniqueOptions) {
@@ -199,6 +208,12 @@ function getValidationSchema(attributes, options = {}) {
   if (allowInclude) {
     schema = schema.append(_include.INCLUDE_FIELD_SCHEMA);
   }
+  if (updateAccess) {
+    return validateAccess('update', schema, updateAccess, {
+      ...options,
+      message: 'You do not have permissions to update this document.'
+    });
+  }
   return schema;
 }
 function getObjectSchema(arg, options) {
@@ -304,10 +319,10 @@ function getSchemaForTypedef(typedef, options = {}) {
     schema = getSearchSchema(schema, type);
   }
   if (typedef.readAccess && options.requireReadAccess) {
-    schema = validateReadAccess(schema, typedef.readAccess, options);
+    schema = validateAccess('read', schema, typedef.readAccess, options);
   }
   if (typedef.writeAccess && options.requireWriteAccess) {
-    schema = validateWriteAccess(schema, typedef.writeAccess, options);
+    schema = validateAccess('write', schema, typedef.writeAccess, options);
   }
   return schema;
 }
@@ -392,13 +407,10 @@ function isExcludedField(field, options) {
   }
   return false;
 }
-function validateReadAccess(schema, allowed, options) {
-  return validateAccess('read', schema, allowed, options);
-}
-function validateWriteAccess(schema, allowed, options) {
-  return validateAccess('write', schema, allowed, options);
-}
 function validateAccess(type, schema, allowed, options) {
+  let {
+    message
+  } = options;
   const {
     modelName
   } = options.model;
@@ -406,7 +418,7 @@ function validateAccess(type, schema, allowed, options) {
     const document = options[(0, _lodash.lowerFirst)(modelName)] || options['document'];
     let isAllowed;
     try {
-      isAllowed = (0, _access.hasAccess)(type, allowed, {
+      isAllowed = (0, _access.hasAccess)(allowed, {
         ...options,
         document
       });
@@ -418,18 +430,27 @@ function validateAccess(type, schema, allowed, options) {
           // against, so continue on to throw a normal permissions error
           // here instead of raising a problem with the implementation.
           isAllowed = false;
-        } else if (type === 'write') {
-          throw new Error(`Write access "${error.name}" requires passing { document, authUser } to the validator.`);
+        } else {
+          throw new Error(`Access validation "${error.name}" requires passing { document, authUser } to the validator.`);
         }
       } else {
         throw error;
       }
     }
     if (!isAllowed) {
-      const currentValue = (0, _lodash.get)(document, options.path);
-      if (val !== currentValue) {
-        throw new _errors.PermissionsError(`requires ${type} permissions.`);
+      const {
+        path
+      } = options;
+      if (path) {
+        if ((0, _lodash.get)(document, path) === val) {
+          // If there is a path being accessed and the current
+          // value is the same as what is being set then do not
+          // throw the error.
+          return;
+        }
+        message ||= `Field "${path.join('.')}" requires ${type} permissions.`;
       }
+      throw new _errors.PermissionsError(message);
     }
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bedrockio/model",
-  "version": "0.2.21",
+  "version": "0.3.0",
   "description": "Bedrock utilities for model creation.",
   "type": "module",
   "scripts": {

package/src/access.js

@@ -1,18 +1,10 @@
 import { ImplementationError } from './errors';
 import warn from './warn';
 
-export function hasReadAccess(allowed, options) {
-  return hasAccess('read', allowed, options);
-}
-
-export function hasWriteAccess(allowed, options) {
-  return hasAccess('write', allowed, options);
-}
-
 /**
  * @param {string|string[]} allowed
  */
-export function hasAccess(type, allowed = 'all', options = {}) {
+export function hasAccess(allowed = 'all', options = {}) {
   if (allowed === 'all') {
     return true;
   } else if (allowed === 'none') {

package/src/include.js

@@ -31,7 +31,7 @@ export function applyInclude(schema) {
   schema.pre(/^find/, function (next) {
     const filter = this.getFilter();
     if (filter.include) {
-      const { select, populate } = getQueryIncludes(this, filter.include);
+      const { select, populate } = getQueryParams(this, filter.include);
       this.select(select);
       this.populate(populate);
       delete filter.include;
@@ -70,7 +70,7 @@ export function applyInclude(schema) {
     this.assign(rest);
 
     if (include) {
-      const { select, populate } = getDocumentIncludes(this, include);
+      const { select, populate } = getDocumentParams(this, include);
       this.$locals.select = select;
       this.$locals.populate = populate;
     }
@@ -89,9 +89,9 @@ export function applyInclude(schema) {
   // Perform population immediately when instance method is called.
   // Store selects as a local variable which will be checked
   // during serialization.
-  schema.method('include', async function include(include) {
+  schema.method('include', async function include(include, options) {
     if (include) {
-      const { select, populate } = getDocumentIncludes(this, include);
+      const { select, populate } = getDocumentParams(this, include, options);
       this.$locals.select = select;
       await this.populate(populate);
     }
@@ -133,18 +133,38 @@ export function checkSelects(doc, ret) {
 }
 
 // Exported for testing.
-export function getIncludes(modelName, arg) {
+export function getParams(modelName, arg) {
   const paths = Array.isArray(arg) ? arg : [arg];
   const node = pathsToNode(paths, modelName);
   return nodeToPopulates(node);
 }
 
-function getQueryIncludes(query, arg) {
-  return getIncludes(query.model.modelName, arg);
+// Exported for testing.
+export function getDocumentParams(doc, arg, options = {}) {
+  const params = getParams(doc.constructor.modelName, arg);
+
+  if (!options.force) {
+    params.populate = params.populate.filter((p) => {
+      return !isDocumentPopulated(doc, p);
+    });
+  }
+
+  return params;
+}
+
+function isDocumentPopulated(doc, params) {
+  if (doc.populated(params.path)) {
+    const sub = doc.get(params.path);
+    return params.populate.every((p) => {
+      return isDocumentPopulated(sub, p);
+    });
+  } else {
+    return false;
+  }
 }
 
-function getDocumentIncludes(doc, arg) {
-  return getIncludes(doc.constructor.modelName, arg);
+function getQueryParams(query, arg) {
+  return getParams(query.model.modelName, arg);
 }
 
 // Note that:

package/src/serialization.js

@@ -1,8 +1,8 @@
 import { isPlainObject } from 'lodash';
 
 import { checkSelects } from './include';
-import { hasReadAccess } from './access';
 import { getField, getInnerField } from './utils';
+import { hasAccess } from './access';
 
 const DISALLOWED_FIELDS = ['deleted', 'deletedRefs'];
 
@@ -60,7 +60,7 @@ function isAllowedField(key, field, options) {
   } else {
     const { readAccess } = getField(field, key);
     try {
-      return hasReadAccess(readAccess, options);
+      return hasAccess(readAccess, options);
     } catch {
       return false;
     }

package/src/validation.js

@@ -125,6 +125,7 @@ export function applyValidation(schema, definition) {
         stripTimestamps: true,
         allowExpandedRefs: true,
         requireWriteAccess: true,
+        updateAccess: definition.access?.update,
         ...(hasUnique && {
           assertUniqueOptions: {
             schema,
@@ -135,6 +136,14 @@ export function applyValidation(schema, definition) {
     }
   );
 
+  schema.static('getDeleteValidation', function getDeleteValidation() {
+    const allowed = definition.access?.delete || 'all';
+    return validateAccess('delete', yd, allowed, {
+      model: this,
+      message: 'You do not have permissions to delete this document.',
+    });
+  });
+
   schema.static(
     'getSearchValidation',
     function getSearchValidation(options = {}) {
@@ -192,7 +201,8 @@ function getMongooseFields(schema, options) {
 
 // Exported for testing
 export function getValidationSchema(attributes, options = {}) {
-  const { appendSchema, assertUniqueOptions, allowInclude } = options;
+  const { appendSchema, assertUniqueOptions, allowInclude, updateAccess } =
+    options;
   let schema = getObjectSchema(attributes, options);
   if (assertUniqueOptions) {
     schema = schema.custom(async (obj, { root }) => {
@@ -208,6 +218,14 @@ export function getValidationSchema(attributes, options = {}) {
   if (allowInclude) {
     schema = schema.append(INCLUDE_FIELD_SCHEMA);
   }
+
+  if (updateAccess) {
+    return validateAccess('update', schema, updateAccess, {
+      ...options,
+      message: 'You do not have permissions to update this document.',
+    });
+  }
+
   return schema;
 }
 
@@ -321,10 +339,10 @@ function getSchemaForTypedef(typedef, options = {}) {
     schema = getSearchSchema(schema, type);
   }
   if (typedef.readAccess && options.requireReadAccess) {
-    schema = validateReadAccess(schema, typedef.readAccess, options);
+    schema = validateAccess('read', schema, typedef.readAccess, options);
   }
   if (typedef.writeAccess && options.requireWriteAccess) {
-    schema = validateWriteAccess(schema, typedef.writeAccess, options);
+    schema = validateAccess('write', schema, typedef.writeAccess, options);
   }
   return schema;
 }
@@ -449,22 +467,15 @@ function isExcludedField(field, options) {
   return false;
 }
 
-function validateReadAccess(schema, allowed, options) {
-  return validateAccess('read', schema, allowed, options);
-}
-
-function validateWriteAccess(schema, allowed, options) {
-  return validateAccess('write', schema, allowed, options);
-}
-
 function validateAccess(type, schema, allowed, options) {
+  let { message } = options;
   const { modelName } = options.model;
   return schema.custom((val, options) => {
     const document = options[lowerFirst(modelName)] || options['document'];
 
     let isAllowed;
     try {
-      isAllowed = hasAccess(type, allowed, {
+      isAllowed = hasAccess(allowed, {
         ...options,
         document,
       });
@@ -476,9 +487,9 @@ function validateAccess(type, schema, allowed, options) {
           // against, so continue on to throw a normal permissions error
           // here instead of raising a problem with the implementation.
           isAllowed = false;
-        } else if (type === 'write') {
+        } else {
           throw new Error(
-            `Write access "${error.name}" requires passing { document, authUser } to the validator.`
+            `Access validation "${error.name}" requires passing { document, authUser } to the validator.`
           );
         }
       } else {
@@ -487,10 +498,17 @@ function validateAccess(type, schema, allowed, options) {
     }
 
     if (!isAllowed) {
-      const currentValue = get(document, options.path);
-      if (val !== currentValue) {
-        throw new PermissionsError(`requires ${type} permissions.`);
+      const { path } = options;
+      if (path) {
+        if (get(document, path) === val) {
+          // If there is a path being accessed and the current
+          // value is the same as what is being set then do not
+          // throw the error.
+          return;
+        }
+        message ||= `Field "${path.join('.')}" requires ${type} permissions.`;
       }
+      throw new PermissionsError(message);
     }
   });
 }

package/types/access.d.ts

@@ -1,7 +1,5 @@
-export function hasReadAccess(allowed: any, options: any): boolean;
-export function hasWriteAccess(allowed: any, options: any): boolean;
 /**
  * @param {string|string[]} allowed
  */
-export function hasAccess(type: any, allowed?: string | string[], options?: {}): boolean;
+export function hasAccess(allowed?: string | string[], options?: {}): boolean;
 //# sourceMappingURL=access.d.ts.map

package/types/access.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.js"],"names":[],"mappings":"AAGA,mEAEC;AAED,oEAEC;AAED;;GAEG;AACH,+CAFW,MAAM,GAAC,MAAM,EAAE,yBA2BzB"}
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.js"],"names":[],"mappings":"AAGA;;GAEG;AACH,oCAFW,MAAM,GAAC,MAAM,EAAE,yBA2BzB"}

package/types/include.d.ts

@@ -1,6 +1,7 @@
 export function applyInclude(schema: any): void;
 export function checkSelects(doc: any, ret: any): void;
-export function getIncludes(modelName: any, arg: any): any;
+export function getParams(modelName: any, arg: any): any;
+export function getDocumentParams(doc: any, arg: any, options?: {}): any;
 export const INCLUDE_FIELD_SCHEMA: {
     setup: any;
     getFields: any;

package/types/include.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"include.d.ts","sourceRoot":"","sources":["../src/include.js"],"names":[],"mappings":"AA2BA,gDAuEC;AAMD,uDA4BC;AAGD,2DAIC;AAvHD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKG"}
+{"version":3,"file":"include.d.ts","sourceRoot":"","sources":["../src/include.js"],"names":[],"mappings":"AA2BA,gDAuEC;AAMD,uDA4BC;AAGD,yDAIC;AAGD,yEAUC;AApID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKG"}

package/types/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.js"],"names":[],"mappings":"AAkFA,kDAEC;AAED,oEAqFC;AAsBD,wEAkBC;AAgSD;;;EAEC;AAED;;;EAOC;AA5eD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQK"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.js"],"names":[],"mappings":"AAkFA,kDAEC;AAED,oEA8FC;AAsBD,wEA2BC;AAgSD;;;EAEC;AAED;;;EAOC;AA9fD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQK"}