adapt-authoring-jsonschema 0.0.1

package/lib/JsonSchemaModule.js

@@ -0,0 +1,209 @@
+import _ from 'lodash'
+import { AbstractModule, Hook } from 'adapt-authoring-core'
+import Ajv from 'ajv/dist/2020.js'
+import { glob } from 'glob'
+import JsonSchema from './JsonSchema.js'
+import Keywords from './Keywords.js'
+import path from 'path'
+import safeRegex from 'safe-regex'
+import XSSDefaults from './XSSDefaults.js'
+
+const BASE_SCHEMA_PATH = './schema/base.schema.json'
+/**
+ * Module which add support for the JSON Schema specification
+ * @memberof jsonschema
+ * @extends {AbstractModule}
+ */
+class JsonSchemaModule extends AbstractModule {
+  /** @override */
+  async init () {
+    this.app.jsonschema = this
+    /**
+     * Reference to all registed schemas
+     * @type {Object}
+     */
+    this.schemas = {}
+    /**
+     * Temporary store of extension schemas
+     * @type {Object}
+     */
+    this.schemaExtensions = {}
+    /**
+     * Invoked when schemas are registered
+     * @type {Hook}
+     */
+    this.registerSchemasHook = new Hook
+    /**
+     * Tags and attributes to be whitelisted by the XSS filter
+     * @type {Object}
+     */
+    this.xssWhitelist = {}
+    /**
+     * Reference to the Ajv instance
+     * @type {external:Ajv}
+     */
+    this.validator = new Ajv({
+      addUsedSchema: false,
+      allErrors: true,
+      allowUnionTypes: true,
+      loadSchema: this.getSchema.bind(this),
+      removeAdditional: 'all',
+      strict: false,
+      verbose: true,
+      keywords: Keywords.all
+    })
+    this.addStringFormats({
+      'date-time': /[A-za-z0-9:+\(\)]+/,
+      time: /^(\d{2}):(\d{2}):(\d{2})\+(\d{2}):(\d{2})$/,
+      uri: /^(.+):\/\/(www\.)?[-a-zA-Z0-9@:%_\+.~#?&//=]{1,256}/
+    })
+    await this.resetSchemaRegistry()
+
+    this.onReady()
+      .then(() => this.app.waitForModule('config', 'errors'))
+      .then(() => {
+        Object.assign(this.xssWhitelist,
+          this.getConfig('xssWhitelistOverride') ? {} : XSSDefaults,
+          this.getConfig('xssWhitelist'))
+      })
+      .then(() => this.addStringFormats(this.getConfig('formatOverrides')))
+      .then(() => this.registerSchemas())
+      .catch(e => this.log('error', e))
+  }
+
+  /**
+   * Empties the schema registry (with the exception of the base schema)
+   */
+  async resetSchemaRegistry () {
+    this.log('debug', 'RESET_SCHEMAS')
+    this.schemas = {
+      base: await this.createSchema(path.resolve(this.rootDir, BASE_SCHEMA_PATH), { enableCache: true })
+    }
+  }
+
+  /**
+   * Adds string formats to the Ajv validator
+   */
+  addStringFormats (formats) {
+    Object.entries(formats).forEach(([name, re]) => {
+      const isUnsafe = !safeRegex(re)
+      if (isUnsafe) this.log('warn', `unsafe RegExp for format '${name}' (${re}), using default`)
+      this.validator.addFormat(name, isUnsafe ? /.*/ : re)
+    })
+  }
+
+  /**
+   * Adds a new keyword to be used in JSON schemas
+   * @param {AjvKeyword} definition
+   */
+  addKeyword (definition) {
+    try {
+      this.validator.addKeyword(definition)
+    } catch (e) {
+      this.log('warn', `failed to define keyword '${definition.keyword}', ${e}`)
+    }
+  }
+
+  /**
+   * Searches all Adapt dependencies for any local JSON schemas and registers them for use in the app. Schemas must be located in in a `/schema` folder, and be named appropriately: `*.schema.json`.
+   * @return {Promise}
+   */
+  async registerSchemas () {
+    await this.resetSchemaRegistry()
+    await Promise.all(Object.values(this.app.dependencies).map(async d => {
+      if(d.name === this.name) return
+      const files = await glob('schema/*.schema.json', { cwd: d.rootDir, absolute: true })
+      ;(await Promise.allSettled(files.map(f => this.registerSchema(f))))
+        .filter(r => r.status === 'rejected')
+        .forEach(r => this.log('warn', r.reason))
+    }))
+    this.registerSchemasHook.invoke();
+  }
+
+  /**
+   * Registers a single JSON schema for use in the app
+   * @param {String} filePath Path to the schema file
+   * @param {RegisterSchemaOptions} options Extra options
+   * @return {Promise}
+   */
+  async registerSchema (filePath, options = {}) {
+    if (!_.isString(filePath)) {
+      throw this.app.errors.INVALID_PARAMS.setData({ params: ['filePath'] })
+    }
+    const schema = await this.createSchema(filePath, options)
+
+    if (this.schemas[schema.name]) {
+      if (options.replace) this.deregisterSchema(schema.name)
+      else throw this.app.errors.SCHEMA_EXISTS.setData({ schemaName: schema.name, filePath })
+    }
+    this.schemas[schema.name] = schema
+    this.schemaExtensions?.[schema.name]?.forEach(s => schema.addExtension(s))
+    if (schema.raw.$patch) this.extendSchema(schema.raw.$patch?.source?.$ref, schema.name)
+
+    this.log('debug', 'REGISTER_SCHEMA', schema.name, filePath)
+  }
+
+  /**
+   * deregisters a single JSON schema
+   * @param {String} name Schem name to deregister
+   * @return {Promise} Resolves with schema data
+   */
+  deregisterSchema (name) {
+    if (this.schemas[name]) delete this.schemas[name]
+    // remove schema from any extensions lists
+    Object.entries(this.schemaExtensions).forEach(([base, extensions]) => {
+      this.schemaExtensions[base] = extensions.filter(s => s !== name)
+    })
+    this.log('debug', 'DEREGISTER_SCHEMA', name)
+  }
+
+  /**
+   * Creates a new JsonSchema instance
+   * @param {String} filePath Path to the schema file
+   * @param {Object} options Options passed to JsonSchema constructor
+   * @returns {JsonSchema}
+   */
+  createSchema (filePath, options) {
+    const schema = new JsonSchema({
+      enableCache: this.getConfig('enableCache'),
+      filePath,
+      validator: this.validator,
+      xssWhitelist: this.xssWhitelist,
+      ...options
+    })
+    this.schemaExtensions?.[schema.name]?.forEach(s => schema.addExtension(s))
+    delete this.schemaExtensions?.[schema.name]
+    return schema.load()
+  }
+
+  /**
+   * Extends an existing schema with extra properties
+   * @param {String} baseSchemaName The name of the schema to extend
+   * @param {String} extSchemaName The name of the schema to extend with
+   */
+  extendSchema (baseSchemaName, extSchemaName) {
+    const baseSchema = this.schemas[baseSchemaName]
+    if (baseSchema) {
+      baseSchema.addExtension(extSchemaName)
+    } else {
+      if (!this.schemaExtensions[baseSchemaName]) this.schemaExtensions[baseSchemaName] = []
+      this.schemaExtensions[baseSchemaName].push(extSchemaName)
+    }
+    this.log('debug', 'EXTEND_SCHEMA', baseSchemaName, extSchemaName)
+  }
+
+  /**
+   * Retrieves the specified schema. Recursively applies any schema merge/patch schemas. Will returned cached data if enabled.
+   * @param {String} schemaName The name of the schema to return
+   * @param {LoadSchemaOptions} options
+   * @param {Boolean} options.compiled If false, the raw schema will be returned
+   * @return {Promise} The compiled schema validation function (default) or the raw schema
+   */
+  async getSchema (schemaName, options = {}) {
+    const schema = this.schemas[schemaName]
+    if (!schema) throw this.app.errors.MISSING_SCHEMA.setData({ schemaName })
+    return schema.build(options)
+  }
+}
+
+export default JsonSchemaModule

package/lib/Keywords.js

@@ -0,0 +1,74 @@
+import { App } from 'adapt-authoring-core'
+import bytes from 'bytes'
+import ms from 'ms'
+import path from 'path'
+/**
+ * Adds some useful schema keywords
+ * @memberof jsonschema
+ * @extends {AbstractModule}
+ */
+class Keywords {
+  static get all () {
+    const keywords = {
+      isBytes: function () {
+        return (value, { parentData, parentDataProperty }) => {
+          try {
+            parentData[parentDataProperty] = bytes.parse(value)
+            return true
+          } catch (e) {
+            return false
+          }
+        }
+      },
+      isDate: function () {
+        return (value, { parentData, parentDataProperty }) => {
+          try {
+            parentData[parentDataProperty] = new Date(value)
+            return true
+          } catch (e) {
+            return false
+          }
+        }
+      },
+      isDirectory: function () {
+        const doReplace = value => {
+          const app = App.instance
+          return [
+            ['$ROOT', app.rootDir],
+            ['$DATA', app.getConfig('dataDir')],
+            ['$TEMP', app.getConfig('tempDir')]
+          ].reduce((m, [k, v]) => {
+            return m.startsWith(k) ? path.resolve(v, m.replace(k, '').slice(1)) : m
+          }, value)
+        }
+        return (value, { parentData, parentDataProperty }) => {
+          try {
+            parentData[parentDataProperty] = doReplace(value)
+          } catch (e) {}
+          return true
+        }
+      },
+      isTimeMs: function () {
+        return (value, { parentData, parentDataProperty }) => {
+          try {
+            parentData[parentDataProperty] = ms(value)
+            return true
+          } catch (e) {
+            return false
+          }
+        }
+      }
+    }
+    return Object.entries(keywords).map(([keyword, compile]) => {
+      return {
+        keyword,
+        type: 'string',
+        modifying: true,
+        schemaType: 'boolean',
+        compile
+      }
+    })
+  }
+}
+
+export default Keywords

package/lib/XSSDefaults.js

@@ -0,0 +1,142 @@
+export default {
+  a: ['class', 'href', 'target', 'title'],
+  abbr: ['title'],
+  address: [],
+  area: ['alt', 'coords', 'href', 'shape'],
+  article: [],
+  aside: ['aria-hidden', 'class', 'role'],
+  audio: [
+    'autoplay',
+    'controls',
+    'crossorigin',
+    'loop',
+    'muted',
+    'preload',
+    'src'
+  ],
+  b: [],
+  bdi: ['dir'],
+  bdo: ['dir'],
+  big: [],
+  blockquote: ['cite'],
+  br: [],
+  button: ['class'],
+  caption: [],
+  center: [],
+  cite: [],
+  code: [],
+  col: ['align', 'span', 'valign', 'width'],
+  colgroup: ['align', 'span', 'valign', 'width'],
+  data: [],
+  dd: [],
+  del: ['datetime'],
+  dfn: [],
+  details: ['open'],
+  div: [
+    'aria-describedby',
+    'aria-description',
+    'aria-label',
+    'aria-hidden',
+    'class',
+    'role',
+    'tabindex'
+  ],
+  dl: [],
+  dt: [],
+  em: [],
+  figcaption: [],
+  figure: ['class'],
+  font: ['color', 'face', 'size'],
+  footer: [],
+  h1: ['class'],
+  h2: ['class'],
+  h3: ['class'],
+  h4: ['class'],
+  h5: ['class'],
+  h6: ['class'],
+  header: [],
+  hr: [],
+  i: [],
+  img: [
+    'alt',
+    'aria-hidden',
+    'aria-label',
+    'class',
+    'height',
+    'loading',
+    'src',
+    'title',
+    'width'
+  ],
+  ins: ['datetime'],
+  kbd: [],
+  li: ['class'],
+  mark: [],
+  math: [],
+  mfrac: [],
+  mi: [],
+  mn: [],
+  mo: [],
+  mover: [],
+  mrow: [],
+  ms: [],
+  mspace: [],
+  msub: [],
+  msubsup: [],
+  msup: [],
+  mtext: [],
+  munder: [],
+  munderover: [],
+  nav: [],
+  ol: ['class'],
+  p: ['lang'],
+  pre: [],
+  q: [],
+  rp: [],
+  rt: [],
+  ruby: [],
+  s: [],
+  samp: [],
+  section: [],
+  small: [],
+  span: [
+    'aria-describedby',
+    'aria-description',
+    'aria-label',
+    'aria-hidden',
+    'class',
+    'role',
+    'tabindex'
+  ],
+  sub: [],
+  summary: [],
+  sup: [],
+  strong: [],
+  strike: [],
+  table: ['align', 'border', 'width', 'valign'],
+  tbody: ['align', 'valign'],
+  td: ['align', 'colspan', 'rowspan', 'valign', 'width'],
+  tfoot: ['align', 'valign'],
+  th: ['align', 'colspan', 'rowspan', 'valign', 'width'],
+  thead: ['align', 'valign'],
+  time: [],
+  tr: ['align', 'rowspan', 'valign'],
+  tt: [],
+  u: [],
+  ul: ['class'],
+  var: [],
+  video: [
+    'autoplay',
+    'controls',
+    'crossorigin',
+    'loop',
+    'muted',
+    'playsinline',
+    'poster',
+    'preload',
+    'src',
+    'height',
+    'width'
+  ],
+  wbr: []
+}

package/lib/typedefs.js

@@ -0,0 +1,48 @@
+/**
+ * This file exists to define the below types for documentation purposes.
+ */
+/**
+ * Ajv JSON Schema validator
+ * @memberof jsonschema
+ * @external Ajv
+ * @see {@link https://ajv.js.org/api.html#ajv-constructor-and-methods}
+ */
+/**
+ * Ajv custom keyword definition
+ * @memberof jsonschema
+ * @external AjvKeyword
+ * @see {@link https://ajv.js.org/keywords.html}
+ */
+/**
+ * @memberof jsonschema
+ * @typedef {Object} ApplyPatchProperties
+ * @property {Object} extendAnnotations Whether annotation properties should be overwitten by the patch
+ * @property {Object} strict Restricts patches to only merge/patch schemas
+ * @property {Object} overwriteProperties Whether existing properties should be overwritten by the patch schema
+*/
+/**
+* @memberof jsonschema
+* @typedef {Object} LoadSchemaOptions
+* @property {Boolean} applyExtensions Whether extension schemas are applied
+* @property {function} extensionFilter Function to selectively apply schema extensions. Function should return a boolean to signify whether the extension should be applied
+* @property {Boolean} useCache Whether cached should be returned
+*/
+/**
+* @memberof jsonschema
+* @typedef {Object} RegisterSchemaOptions
+* @property {Boolean} replace Will replace the existing schema if one exists
+*/
+/**
+* @memberof jsonschema
+* @typedef {Object} SanitiseOptions
+* @property {Boolean} isInternal Whether internal attributes should be filtered
+* @property {Boolean} isReadOnly Whether read-only attributes should be filtered
+* @property {Boolean} sanitiseHtml Whether HTML text should be filtered
+* @property {Boolean} strict Whether to throw errors
+*/
+/**
+* @memberof jsonschema
+* @typedef {Object} ValidateOptions
+* @property {Boolean} useDefaults Whether to apply defaults
+* @property {Boolean} ignoreRequired Whether to ignore missing required fields
+*/

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "adapt-authoring-jsonschema",
+  "version": "0.0.1",
+  "description": "Module to add support for the JSON schema specification",
+  "homepage": "https://github.com/adapt-security/adapt-authoring-jsonschema",
+  "license": "GPL-3.0",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "at-schemacheck": "./bin/check.js"
+  },
+  "repository": "github:adapt-security/adapt-authoring-jsonschema",
+  "dependencies": {
+    "ajv": "^8.12.0",
+    "bytes": "^3.1.2",
+    "glob": "^11.0.0",
+    "lodash": "^4.17.21",
+    "ms": "^2.1.3",
+    "safe-regex": "2.1.1",
+    "xss": "^1.0.14"
+  },
+  "peerDependencies": {
+    "adapt-authoring-core": "github:adapt-security/adapt-authoring-core"
+  },
+  "devDependencies": {
+    "eslint": "^9.12.0",
+    "standard": "^17.1.0"
+  }
+}

package/schema/base.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$anchor": "base",
+  "description": "The base schema inherited by all other schemas",
+  "type": "object",
+  "properties": {
+    "_id": {
+      "description": "Unique identifier",
+      "type": "string",
+      "isObjectId": true
+    }
+  }
+}