adapt-authoring-api 2.1.4 → 2.2.0

package/lib/AbstractApiModule.js

@@ -2,6 +2,7 @@ import _ from 'lodash'
 import { AbstractModule, Hook, stringifyValues } from 'adapt-authoring-core'
 import { argsFromReq, generateApiMetadata, httpMethodToDBFunction } from './utils.js'
 import DataCache from './DataCache.js'
+import { loadRouteConfig } from 'adapt-authoring-server'
 /**
  * Abstract module for creating APIs
  * @memberof api
@@ -149,6 +150,17 @@ class AbstractApiModule extends AbstractModule {
      * @type {String}
      */
     this.schemaName = undefined
+
+    const config = await loadRouteConfig(this.rootDir, this, {
+      schema: 'apiroutes',
+      handlerAliases: {
+        default: this.requestHandler(),
+        query: this.queryHandler(),
+        serveSchema: this.serveSchema.bind(this)
+      },
+      defaults: new URL('./default-routes.json', import.meta.url).pathname
+    })
+    if (config) this.applyRouteConfig(config)
   }
 
   /**
@@ -189,6 +201,7 @@ class AbstractApiModule extends AbstractModule {
 
   /**
    * Checks required values have been set
+   * @deprecated Validation is handled by the routes schema for modules using routes.json
    */
   validateValues () {
     if (!this.root && !this.router) {
@@ -226,6 +239,30 @@ class AbstractApiModule extends AbstractModule {
     Object.values(uniqueRoutes).forEach(r => this.addRoute(r, auth))
   }
 
+  /**
+   * Applies route configuration loaded from routes.json.
+   * Expands `${scope}` permission placeholders with `this.permissionsScope || this.root`.
+   * @param {Object} config The route config object returned by loadRouteConfig
+   */
+  applyRouteConfig (config) {
+    /** @ignore */ this.root = config.root
+    if (config.schemaName !== undefined) this.schemaName = config.schemaName
+    if (config.collectionName !== undefined) this.collectionName = config.collectionName
+    const scope = this.permissionsScope || this.root
+    this.routes = config.routes.map(r => {
+      if (!r.permissions) return r
+      return {
+        ...r,
+        permissions: Object.fromEntries(
+          Object.entries(r.permissions).map(([method, perms]) => [
+            method,
+            Array.isArray(perms) ? perms.map(p => p.replace('${scope}', scope)) : perms // eslint-disable-line no-template-curly-in-string
+          ])
+        )
+      }
+    })
+  }
+
   /**
    * Adds a single route definition
    * @param {Route} config The route config

package/lib/default-routes.json

@@ -0,0 +1,26 @@
+{
+  "routes": [
+    {
+      "route": "/",
+      "handlers": { "post": "default", "get": "default" },
+      "permissions": { "post": ["write:${scope}"], "get": ["read:${scope}"] }
+    },
+    {
+      "route": "/schema",
+      "handlers": { "get": "serveSchema" },
+      "permissions": { "get": ["read:schema"] }
+    },
+    {
+      "route": "/:_id",
+      "handlers": { "put": "default", "get": "default", "patch": "default", "delete": "default" },
+      "permissions": { "put": ["write:${scope}"], "get": ["read:${scope}"], "patch": ["write:${scope}"], "delete": ["write:${scope}"] }
+    },
+    {
+      "route": "/query",
+      "validate": false,
+      "modifying": false,
+      "handlers": { "post": "query" },
+      "permissions": { "post": ["read:${scope}"] }
+    }
+  ]
+}

package/lib/utils/generateApiMetadata.js

@@ -2,6 +2,7 @@
  * Generates REST API metadata and stores on route config
  * @param {AbstractApiModule} instance The current AbstractApiModule instance
  * @memberof api
+ * @deprecated For modules with routes.json, define metadata in the meta field of each route entry instead
  */
 export function generateApiMetadata (instance) {
   const getData = isList => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-api",
-  "version": "2.1.4",
+  "version": "2.2.0",
   "description": "Abstract module for creating APIs",
   "homepage": "https://github.com/adapt-security/adapt-authoring-api",
   "license": "GPL-3.0",
@@ -18,10 +18,11 @@
     "adapt-authoring-auth": "^2.0.0",
     "adapt-authoring-jsonschema": "^1.2.0",
     "adapt-authoring-mongodb": "^3.0.0",
-    "adapt-authoring-server": "^2.0.0"
+    "adapt-authoring-server": "^2.1.0"
   },
   "devDependencies": {
     "@semantic-release/git": "^10.0.1",
+    "adapt-authoring-server": "^2.1.0",
     "conventional-changelog-eslint": "^6.0.0",
     "semantic-release": "^25.0.2",
     "standard": "^17.1.0"

package/schema/apiroutes.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$anchor": "apiroutes",
+  "$merge": {
+    "source": { "$ref": "routes" },
+    "with": {
+      "properties": {
+        "schemaName": {
+          "type": "string",
+          "description": "Schema name for the module's data model"
+        },
+        "collectionName": {
+          "type": "string",
+          "description": "MongoDB collection name"
+        },
+        "useDefaultRoutes": {
+          "type": "boolean",
+          "description": "Whether to generate default CRUD routes",
+          "default": true
+        },
+        "routes": {
+          "type": "array",
+          "items": { "$ref": "routeitem" }
+        }
+      }
+    }
+  }
+}

package/tests/AbstractApiModule.spec.js

@@ -2,6 +2,20 @@ import { describe, it } from 'node:test'
 import assert from 'node:assert/strict'
 import AbstractApiModule from '../lib/AbstractApiModule.js'
 
+function createInstance (overrides = {}) {
+  const instance = Object.create(AbstractApiModule.prototype)
+  instance.root = 'test'
+  instance.permissionsScope = undefined
+  instance.schemaName = undefined
+  instance.collectionName = undefined
+  instance.routes = []
+  instance.requestHandler = () => function defaultRequestHandler () {}
+  instance.queryHandler = () => function queryHandler () {}
+  instance.serveSchema = function serveSchema () {}
+  Object.assign(instance, overrides)
+  return instance
+}
+
 describe('AbstractApiModule', () => {
   describe('#mapStatusCode()', () => {
     const instance = Object.create(AbstractApiModule.prototype)
@@ -56,4 +70,112 @@ describe('AbstractApiModule', () => {
       assert.equal(options, undefined)
     })
   })
+
+  describe('#applyRouteConfig()', () => {
+    it('should set root, schemaName, and collectionName from config', async () => {
+      const instance = createInstance()
+      await instance.applyRouteConfig({
+        root: 'content',
+        schemaName: 'content',
+        collectionName: 'content',
+        useDefaultRoutes: false,
+        routes: []
+      })
+      assert.equal(instance.root, 'content')
+      assert.equal(instance.schemaName, 'content')
+      assert.equal(instance.collectionName, 'content')
+    })
+
+    it('should not override schemaName or collectionName when not in config', async () => {
+      const instance = createInstance({ schemaName: 'existing', collectionName: 'existing' })
+      await instance.applyRouteConfig({ root: 'content', useDefaultRoutes: false, routes: [] })
+      assert.equal(instance.schemaName, 'existing')
+      assert.equal(instance.collectionName, 'existing')
+    })
+
+    it('should set routes to custom routes only when useDefaultRoutes is false', async () => {
+      const instance = createInstance()
+      const customRoute = { route: '/custom', handlers: { get: () => {} } }
+      await instance.applyRouteConfig({ root: 'test', useDefaultRoutes: false, routes: [customRoute] })
+      assert.equal(instance.routes.length, 1)
+      assert.equal(instance.routes[0].route, '/custom')
+    })
+
+    it('should set routes to empty array when config has no routes', async () => {
+      const instance = createInstance()
+      await instance.applyRouteConfig({ root: 'test', routes: [] })
+      assert.deepEqual(instance.routes, [])
+    })
+
+    it('should expand ${scope} placeholders in permissions using root', async () => { // eslint-disable-line no-template-curly-in-string
+      const instance = createInstance({ root: 'content' })
+      await instance.applyRouteConfig({
+        root: 'content',
+        routes: [{ route: '/', permissions: { get: ['read:${scope}'], post: ['write:${scope}'] } }] // eslint-disable-line no-template-curly-in-string
+      })
+      assert.deepEqual(instance.routes[0].permissions.get, ['read:content'])
+      assert.deepEqual(instance.routes[0].permissions.post, ['write:content'])
+    })
+
+    it('should prefer permissionsScope over root for ${scope} expansion', async () => { // eslint-disable-line no-template-curly-in-string
+      const instance = createInstance({ root: 'content', permissionsScope: 'custom' })
+      await instance.applyRouteConfig({
+        root: 'content',
+        routes: [{ route: '/', permissions: { get: ['read:${scope}'] } }] // eslint-disable-line no-template-curly-in-string
+      })
+      assert.deepEqual(instance.routes[0].permissions.get, ['read:custom'])
+    })
+
+    it('should pass through null permissions unchanged', async () => {
+      const instance = createInstance({ root: 'content' })
+      await instance.applyRouteConfig({
+        root: 'content',
+        routes: [{ route: '/', permissions: { get: null } }]
+      })
+      assert.equal(instance.routes[0].permissions.get, null)
+    })
+  })
+
+  describe('#DEFAULT_ROUTES', () => {
+    it('should return an array of route objects', async () => {
+      const instance = createInstance()
+      const routes = await instance.DEFAULT_ROUTES
+      assert.ok(Array.isArray(routes))
+      assert.ok(routes.length > 0)
+    })
+
+    it('should include routes for /, /schema, /:_id, and /query', async () => {
+      const instance = createInstance()
+      const routes = await instance.DEFAULT_ROUTES
+      const routePaths = routes.map(r => r.route)
+      assert.ok(routePaths.includes('/'))
+      assert.ok(routePaths.includes('/schema'))
+      assert.ok(routePaths.includes('/:_id'))
+      assert.ok(routePaths.includes('/query'))
+    })
+
+    it('should use permissionsScope when set', async () => {
+      const instance = createInstance({ root: 'content', permissionsScope: 'custom' })
+      const routes = await instance.DEFAULT_ROUTES
+      const rootRoute = routes.find(r => r.route === '/')
+      assert.ok(rootRoute.permissions.post.includes('write:custom'))
+      assert.ok(rootRoute.permissions.get.includes('read:custom'))
+    })
+
+    it('should fall back to root for permissions when permissionsScope is not set', async () => {
+      const instance = createInstance({ root: 'content', permissionsScope: undefined })
+      const routes = await instance.DEFAULT_ROUTES
+      const rootRoute = routes.find(r => r.route === '/')
+      assert.ok(rootRoute.permissions.post.includes('write:content'))
+      assert.ok(rootRoute.permissions.get.includes('read:content'))
+    })
+
+    it('should set validate: false and modifying: false on /query route', async () => {
+      const instance = createInstance()
+      const routes = await instance.DEFAULT_ROUTES
+      const queryRoute = routes.find(r => r.route === '/query')
+      assert.equal(queryRoute.validate, false)
+      assert.equal(queryRoute.modifying, false)
+    })
+  })
 })