@bedrock/validation 6.0.0

package/lib/index.js

@@ -0,0 +1,250 @@
+/*!
+ * Copyright (c) 2012-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+import Ajv from 'ajv';
+import {Cache} from './Cache.js';
+import {promises as fs} from 'fs';
+import {logger} from './logger.js';
+import PATH from 'path';
+
+const ajv = new Ajv({cache: new Cache(), serialize: false, verbose: true});
+const {util: {BedrockError}} = bedrock;
+
+// load config defaults
+import './config.js';
+
+// available schemas
+export const schemas = {};
+
+bedrock.events.on('bedrock.init', init);
+
+/**
+ * Initializes the validation system: loads all schemas, etc.
+ */
+async function init() {
+  // schemas to skip loading
+  const skip = bedrock.config.validation.schema.skip.slice();
+
+  // load all schemas in directory order
+  const schemaDirs = bedrock.config.validation.schema.paths;
+  const jsExt = '.js';
+  for(let schemaDir of schemaDirs) {
+    schemaDir = PATH.resolve(schemaDir);
+    logger.debug('loading schemas from: ' + schemaDir);
+    const files = (await fs.readdir(schemaDir)).filter(file => {
+      const js = PATH.extname(file) === jsExt;
+      const use = skip.indexOf(file) === -1;
+      return js && use;
+    });
+    // load files in parallel
+    await Promise.all(files.map(async file => {
+      const name = PATH.basename(file, PATH.extname(file));
+      const module = await import(PATH.join(schemaDir, file));
+      const api = module.default || module;
+      if(typeof api === 'function') {
+        if(name in schemas) {
+          logger.debug(
+            'overwriting schema "' + name + '" with ' +
+            PATH.resolve(schemaDir, file));
+        }
+        schemas[name] = api;
+        schemas[name].instance = api();
+        logger.debug('loaded schema: ' + name);
+      } else {
+        for(const key in api) {
+          const tmp = name + '.' + key;
+          if(tmp in schemas) {
+            logger.debug('overwriting schema "' + tmp + '" with ' + file);
+          }
+          schemas[tmp] = api[key];
+          schemas[tmp].instance = schemas[tmp]();
+          logger.debug('loaded schema: ' + tmp);
+        }
+      }
+    }));
+  }
+}
+
+/**
+ * Compiles the given schema, returning a validation function that takes one
+ * parameter: the data to be validated. It returns the same value that
+ * `validateInstance` returns.
+ *
+ * @param {object} options - The options to use.
+ * @param {object} options.schema - The JSON schema to compile.
+ *
+ * @returns {Function} The a validate function to call on instance data.
+ */
+export function compile({schema} = {}) {
+  const fn = ajv.compile(schema);
+  fn.title = schema.title;
+  return function validate(instance) {
+    if(fn(instance)) {
+      return {valid: true};
+    }
+    return {
+      valid: false,
+      error: _createError({schema: fn, instance})
+    };
+  };
+}
+
+/**
+ * Retrieves a validation schema given a name for the schema.
+ *
+ * @param {object} options - The options to use.
+ * @param {string} options.name - The name of the schema to retrieve.
+ *
+ * @returns {object|null} The object for the schema, or `null` if the schema
+ *   doesn't exist.
+ */
+export function getSchema({name} = {}) {
+  let schema = null;
+  if(name in schemas) {
+    schema = schemas[name].instance;
+  }
+  return schema;
+}
+
+/**
+ * Validates an instance against a schema.
+ *
+ * @param {object} options - The options to use.
+ * @param {*} options.instance - The instance to validate.
+ * @param {object|Array|Function|string} [options.schema] - The JSON schema,
+ *   compiled schema function, or name of schema to use.
+ *
+ * @returns {object} The validation result.
+ */
+export function validateInstance({instance, schema} = {}) {
+  const schemaIsFunction = typeof schema === 'function';
+
+  // do validation
+  let valid;
+  if(schemaIsFunction) {
+    valid = schema(instance);
+  } else {
+    if(typeof schema === 'string') {
+      const name = schema;
+      schema = getSchema({name});
+      if(!schema) {
+        throw new BedrockError(
+          `Could not validate data; unknown schema name (${name}).`,
+          'NotFoundError', {schemaName: name});
+      }
+    }
+    valid = ajv.validate(schema, instance);
+  }
+  if(valid) {
+    return {valid};
+  }
+
+  const result = {
+    valid: false,
+    error: _createError({schema, instance})
+  };
+
+  return result;
+}
+
+/**
+ * Creates middleware that will validate request body and URL query parameters.
+ *
+ * Use this method over the deprecated `validate` to create a middleware.
+ *
+ * @param {object} options - The options to use.
+ * @param {object} [options.bodySchema] - The JSON schema to use to validate
+ *   the request body.
+ * @param {object} [options.querySchema] - The JSON schema to use to validate
+ *   the request URL query parameters.
+ *
+ * @returns {Function} An express-style middleware.
+ */
+export function createValidateMiddleware({bodySchema, querySchema} = {}) {
+  if(!(bodySchema || querySchema)) {
+    throw new TypeError(
+      'One of the following parameters is required: ' +
+      '"bodySchema", "querySchema".');
+  }
+  // pre-compile schemas
+  let validateBodySchema;
+  if(bodySchema) {
+    validateBodySchema = compile({schema: bodySchema});
+  }
+  let validateQuerySchema;
+  if(querySchema) {
+    validateQuerySchema = compile({schema: querySchema});
+  }
+  return function validate(req, res, next) {
+    if(validateBodySchema) {
+      const result = validateBodySchema(req.body);
+      if(!result.valid) {
+        return next(result.error);
+      }
+    }
+    if(validateQuerySchema) {
+      const result = validateQuerySchema(req.query);
+      if(!result.valid) {
+        return next(result.error);
+      }
+    }
+    next();
+  };
+}
+
+function _createError({schema, instance}) {
+  // create public error messages
+  const schemaIsFunction = typeof schema === 'function';
+  const validationErrors = schemaIsFunction ? schema.errors : ajv.errors;
+  const errors = [];
+  for(const error of validationErrors) {
+    // create custom error details
+    const details = {
+      instance,
+      params: error.params,
+      path: error.dataPath,
+      public: true,
+      schemaPath: error.schemaPath,
+    };
+    let title;
+    if(Array.isArray(error.schema)) {
+      [title] = error.schema;
+    }
+    title = title || error.parentSchema.title || '',
+    details.schema = {
+      description: error.parentSchema.description || '',
+      title,
+    };
+    // include custom errors or use default
+    // FIXME: enable if ajv supports this parentSchema.errors property
+    // it appears that this is not the case
+    // details.errors = error.parentSchema.errors || {
+    //   invalid: 'Invalid input.',
+    //   missing: 'Missing input.'
+    // };
+    if(error.data) {
+      if(error.parentSchema.errors && 'mask' in error.parentSchema.errors) {
+        const mask = error.parentSchema.errors.mask;
+        if(mask === true) {
+          details.value = '***MASKED***';
+        } else {
+          details.value = mask;
+        }
+      } else {
+        details.value = error.data;
+      }
+    }
+
+    // add bedrock validation error
+    errors.push(new BedrockError(error.message, 'ValidationError', details));
+  }
+
+  const msg = schema.title ?
+    'A validation error occured in the \'' + schema.title + '\' validator.' :
+    'A validation error occured in an unnamed validator.';
+  const error = new BedrockError(
+    msg, 'ValidationError', {public: true, errors, httpStatusCode: 400});
+
+  return error;
+}

package/lib/logger.js

@@ -0,0 +1,5 @@
+/*!
+ * Copyright (c) 2018-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import {loggers} from '@bedrock/core';
+export const logger = loggers.get('app').child('bedrock-validation');

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@bedrock/validation",
+  "version": "6.0.0",
+  "type": "module",
+  "description": "Bedrock validation",
+  "main": "./lib/index.js",
+  "scripts": {
+    "lint": "eslint ."
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/digitalbazaar/bedrock-validation"
+  },
+  "keywords": [
+    "bedrock"
+  ],
+  "author": {
+    "name": "Digital Bazaar, Inc.",
+    "email": "support@digitalbazaar.com",
+    "url": "http://digitalbazaar.com"
+  },
+  "bugs": {
+    "url": "https://github.com/digitalbazaar/bedrock-validation/issues"
+  },
+  "homepage": "https://github.com/digitalbazaar/bedrock-validation",
+  "dependencies": {
+    "ajv": "^6.12.0"
+  },
+  "peerDependencies": {
+    "@bedrock/core": "^5.0.0"
+  },
+  "directories": {
+    "lib": "./lib"
+  },
+  "devDependencies": {
+    "eslint": "^7.32.0",
+    "eslint-config-digitalbazaar": "^2.8.0",
+    "eslint-plugin-jsdoc": "^37.9.7",
+    "jsdoc-to-markdown": "^6.0.1"
+  }
+}

package/schemas/comment.js

@@ -0,0 +1,24 @@
+/*!
+ * Copyright (c) 2012-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+
+const schema = {
+  title: 'Comment',
+  description: 'A short comment.',
+  type: 'string',
+  minLength: 1,
+  maxLength: 5000,
+  errors: {
+    invalid: 'The comment contains invalid characters or is more than ' +
+      '5000 characters in length.',
+    missing: 'Please enter a comment.'
+  }
+};
+
+export default function(extend) {
+  if(extend) {
+    return bedrock.util.extend(true, bedrock.util.clone(schema), extend);
+  }
+  return schema;
+}

package/schemas/credential.js

@@ -0,0 +1,37 @@
+/*!
+ * Copyright (c) 2012-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+import identifier from './identifier.js';
+import jsonldContext from './jsonldContext.js';
+import w3cDateTime from './w3cDateTime.js';
+
+// TODO: Improve this schema
+const schema = {
+  type: 'object',
+  title: 'Credential',
+  properties: {
+    '@context': jsonldContext(),
+    // FIXME: improve credential context check
+    //'@context': schemas.jsonldContext([
+    //  constants.IDENTITY_CONTEXT_V1_URL,
+    //  constants.CREDENTIALS_CONTEXT_V1_URL
+    //]),
+    issuer: identifier(),
+    issued: w3cDateTime(),
+    claim: {
+      required: ['id'],
+      properties: {
+        id: identifier()
+      },
+    }
+  },
+  required: ['issuer', 'issued', 'claim']
+};
+
+export default function(extend) {
+  if(extend) {
+    return bedrock.util.extend(true, bedrock.util.clone(schema), extend);
+  }
+  return schema;
+}

package/schemas/description.js

@@ -0,0 +1,24 @@
+/*!
+ * Copyright (c) 2012-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+
+const schema = {
+  title: 'Description',
+  description: 'A description.',
+  type: 'string',
+  minLength: 0,
+  maxLength: 5000,
+  errors: {
+    invalid: 'The description contains invalid characters or is more than ' +
+      '5000 characters in length.',
+    missing: 'Please enter a description.'
+  }
+};
+
+export default function(extend) {
+  if(extend) {
+    return bedrock.util.extend(true, bedrock.util.clone(schema), extend);
+  }
+  return schema;
+}

package/schemas/email.js

@@ -0,0 +1,34 @@
+/*!
+ * Copyright (c) 2012-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+
+// RFC 1034 - All labels have a max length of 63 octets.
+// https://tools.ietf.org/html/rfc1034#section-3.1
+const schema = {
+  title: 'Email',
+  description: 'An email address.',
+  type: 'string',
+  // eslint-disable-next-line max-len
+  pattern: '^[-a-z0-9~!$%^&*_=+}{\\\'?]+(\\.[-a-z0-9~!$%^&*_=+}{\\\'?]+)*@(((([a-z0-9]{1}[a-z0-9\\-]{0,63}[a-z0-9]{1})|[a-z])\\.)+[a-z]{2,63})$',
+  minLength: 1,
+  maxLength: 100,
+  errors: {
+    invalid: 'The email address is invalid.',
+    missing: 'Please enter an email address.'
+  }
+};
+
+export default function(extend, options) {
+  if(options && options.lowerCaseOnly) {
+    extend = extend || {};
+    if(!('pattern' in extend)) {
+      // eslint-disable-next-line max-len
+      extend.pattern = '^[-a-z0-9~!$%^&*_=+}{\\\'?]+(\\.[-a-z0-9~!$%^&*_=+}{\\\'?]+)*@(((([a-z0-9]{1}[a-z0-9\\-]{0,63}[a-z0-9]{1})|[a-z])\\.)+[a-z]{2,63})$';
+    }
+  }
+  if(extend) {
+    return bedrock.util.extend(true, bedrock.util.clone(schema), extend);
+  }
+  return schema;
+}

package/schemas/identifier.js

@@ -0,0 +1,22 @@
+/*!
+ * Copyright (c) 2012-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+
+const schema = {
+  title: 'ID',
+  description: 'A unique identifier.',
+  type: 'string',
+  minLength: 1,
+  disallow: {
+    type: 'string',
+    enum: ['0']
+  }
+};
+
+export default function(extend) {
+  if(extend) {
+    return bedrock.util.extend(true, bedrock.util.clone(schema), extend);
+  }
+  return schema;
+}

package/schemas/jsonPatch.js

@@ -0,0 +1,38 @@
+/*!
+ * Copyright (c) 2019-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+
+const schema = {
+  title: 'JSON Patch',
+  type: 'array',
+  minItems: 1,
+  items: {
+    type: 'object',
+    required: ['op', 'path'],
+    // FIXME: more strictly validate properties based on value of `op`
+    properties: {
+      op: {
+        type: 'string',
+        enum: ['add', 'copy', 'move', 'remove', 'replace', 'test']
+      },
+      from: {
+        type: 'string',
+      },
+      path: {
+        type: 'string',
+      },
+      value: {
+        //type: ['number', 'string', 'boolean', 'object', 'array'],
+      }
+    },
+    additionalProperties: false
+  }
+};
+
+export default function(extend) {
+  if(extend) {
+    return bedrock.util.extend(true, bedrock.util.clone(schema), extend);
+  }
+  return schema;
+}

package/schemas/jsonldContext.js

@@ -0,0 +1,54 @@
+/*!
+ * Copyright (c) 2012-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+
+export default function(context, extend) {
+  const schema = {
+    title: 'JSON-LD context',
+    description: 'A JSON-LD Context'
+  };
+  if(!Array.isArray(context)) {
+    schema.anyOf = [{
+      type: 'string'
+      // enum added below if context param truthy
+    }, {
+      type: 'object'
+      // FIXME: improve context object validator
+    }, {
+      type: 'array',
+      // items added below if context param truthy
+    }];
+    if(context) {
+      schema.anyOf[0].enum = [context];
+      schema.anyOf[2].items = [{const: context}];
+      schema.anyOf[2].additionalItems = false;
+    }
+  } else {
+    Object.assign(schema, {
+      type: 'array',
+      minItems: context.length,
+      uniqueItems: true,
+      items: [],
+      errors: {
+        invalid: 'The JSON-LD context information is invalid.',
+        missing: 'The JSON-LD context information is missing.'
+      }
+    });
+    for(let i = 0; i < context.length; ++i) {
+      if(typeof context[i] === 'string') {
+        schema.items.push({
+          type: 'string',
+          enum: [context[i]]
+        });
+      } else {
+        // FIXME: improve context object validator
+        schema.items.push({type: 'object'});
+      }
+    }
+  }
+  if(extend) {
+    return bedrock.util.extend(true, bedrock.util.clone(schema), extend);
+  }
+  return schema;
+}

package/schemas/jsonldType.js

@@ -0,0 +1,72 @@
+/*!
+ * Copyright (c) 2012-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+export default function(types, alternates) {
+  const schema = {
+    title: 'Object Type',
+    description: 'A set of terms, CURIEs, or URLs specifying the type of ' +
+      'the object.',
+    anyOf: []
+  };
+
+  types = Array.isArray(types) ? types : [types];
+
+  // allow single object
+  if(types.length === 1) {
+    schema.anyOf.push({
+      type: 'string',
+      enum: types,
+      errors: {
+        invalid: 'The JSON-LD type information is invalid.',
+        missing: 'The JSON-LD type information is missing.'
+      }
+    });
+  }
+
+  // allow array combination of all types
+  schema.anyOf.push({
+    type: 'array',
+    // minItems: types.length,
+    uniqueItems: true,
+    items: {
+      type: 'string',
+      enum: types
+    },
+    errors: {
+      invalid: 'The JSON-LD type information is invalid.',
+      missing: 'The JSON-LD type information is missing.'
+    }
+  });
+
+  // HACK: madness to support given types *must* exist, while allowing
+  // up to <alternates> other custom types
+  if(alternates !== undefined) {
+    for(let before = 0; before <= alternates; ++before) {
+      const s = {
+        type: 'array',
+        minItems: types.length,
+        uniqueItems: true,
+        items: [],
+        additionalItems: {
+          type: 'string'
+        },
+        errors: {
+          invalid: 'The JSON-LD type information is invalid.',
+          missing: 'The JSON-LD type information is missing.'
+        }
+      };
+      for(let i = 0; i < before; ++i) {
+        s.items.push({type: 'string'});
+      }
+      for(let i = 0; i < types.length; ++i) {
+        s.items.push({
+          type: 'string',
+          enum: types
+        });
+      }
+      schema.anyOf.push(s);
+    }
+  }
+
+  return schema;
+}

package/schemas/label.js

@@ -0,0 +1,25 @@
+/*!
+ * Copyright (c) 2012-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+
+const schema = {
+  title: 'Label',
+  description: 'A short, descriptive label.',
+  type: 'string',
+  pattern: '^[-a-zA-Z0-9~`!@#$%^&*\\(\\)\\[\\]{}<>_=+\\\\|:;\'"\\.,/? ]*$',
+  minLength: 1,
+  maxLength: 200,
+  errors: {
+    invalid: 'The label contains invalid characters or is not between ' +
+      '1 and 200 characters in length.',
+    missing: 'Please enter a label.'
+  }
+};
+
+export default function(extend) {
+  if(extend) {
+    return bedrock.util.extend(true, bedrock.util.clone(schema), extend);
+  }
+  return schema;
+}

package/schemas/linkedDataSignature.js

@@ -0,0 +1,46 @@
+/*!
+ * Copyright (c) 2012-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+import identifier from './identifier.js';
+import w3cDateTime from './w3cDateTime.js';
+
+const signature = {
+  title: 'Linked Data Signature',
+  description: 'A Linked Data digital signature.',
+  type: 'object',
+  properties: {
+    id: identifier(),
+    type: {
+      title: 'Linked Data Signature Type',
+      type: 'string',
+      enum: ['LinkedDataSignature2015', 'LinkedDataSignature2016']
+    },
+    creator: identifier(),
+    created: w3cDateTime(),
+    signatureValue: {
+      title: 'Digital Signature Value',
+      description: 'The Base64 encoding of the result of the signature ' +
+        'algorithm.',
+      type: 'string'
+    },
+  },
+  // NOTE: id is not required
+  required: ['type', 'creator', 'created', 'signatureValue']
+};
+
+const schema = {
+  title: 'Linked Data Signatures',
+  anyOf: [{
+    type: 'array',
+    items: signature,
+    minItems: 1,
+  }, signature]
+};
+
+export default function(extend) {
+  if(extend) {
+    return bedrock.util.extend(true, bedrock.util.clone(schema), extend);
+  }
+  return schema;
+}