@bedrockio/model 0.2.22 → 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/include.js

@@ -99,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
-      } = getDocumentParams(this, include);
+      } = getDocumentParams(this, include, options);
       this.$locals.select = select;
       await this.populate(populate);
     }
@@ -155,11 +155,13 @@ function getParams(modelName, arg) {
 }
 
 // Exported for testing.
-function getDocumentParams(doc, arg) {
+function getDocumentParams(doc, arg, options = {}) {
   const params = getParams(doc.constructor.modelName, arg);
-  params.populate = params.populate.filter(p => {
-    return !isDocumentPopulated(doc, p);
-  });
+  if (!options.force) {
+    params.populate = params.populate.filter(p => {
+      return !isDocumentPopulated(doc, p);
+    });
+  }
   return params;
 }
 function isDocumentPopulated(doc, params) {

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;
@@ -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.22",
+  "version": "0.3.0",
   "description": "Bedrock utilities for model creation.",
   "type": "module",
   "scripts": {

package/src/include.js

@@ -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 } = getDocumentParams(this, include);
+      const { select, populate } = getDocumentParams(this, include, options);
       this.$locals.select = select;
       await this.populate(populate);
     }
@@ -140,11 +140,15 @@ export function getParams(modelName, arg) {
 }
 
 // Exported for testing.
-export function getDocumentParams(doc, arg) {
+export function getDocumentParams(doc, arg, options = {}) {
   const params = getParams(doc.constructor.modelName, arg);
-  params.populate = params.populate.filter((p) => {
-    return !isDocumentPopulated(doc, p);
-  });
+
+  if (!options.force) {
+    params.populate = params.populate.filter((p) => {
+      return !isDocumentPopulated(doc, p);
+    });
+  }
+
   return params;
 }
 

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,15 +467,8 @@ 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'];
@@ -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/include.d.ts

@@ -1,7 +1,7 @@
 export function applyInclude(schema: any): void;
 export function checkSelects(doc: any, ret: any): void;
 export function getParams(modelName: any, arg: any): any;
-export function getDocumentParams(doc: 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,yDAIC;AAGD,2DAMC;AAhID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}