adapt-authoring-server 2.0.1 → 2.2.0

package/docs/server-requests.md

@@ -1,8 +1,69 @@
 # Handling server requests
-This page gives you some pointers on how to handle incoming requests in a way that will reduce the work needed by you as a developer, and create consistent and easy-to-process responses. 
+This page gives you some pointers on how to handle incoming requests in a way that will reduce the work needed by you as a developer, and create consistent and easy-to-process responses.
+
+## Defining routes with `routes.json`
+
+For modules that expose HTTP endpoints, the preferred approach is to declare routes in a `routes.json` file in the module root. This keeps route definitions, permissions, and API metadata in one place.
+
+```json
+{
+  "root": "mymodule",
+  "routes": [
+    {
+      "route": "/action",
+      "handlers": { "post": "actionHandler" },
+      "permissions": { "post": ["write:myresource"] },
+      "meta": {
+        "post": {
+          "summary": "Perform an action",
+          "requestBody": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "name": { "type": "string" }
+                  }
+                }
+              }
+            }
+          },
+          "responses": { "204": {} }
+        }
+      }
+    }
+  ]
+}
+```
+
+Then in your module code, use `loadRouteConfig` and `registerRoutes` to load and wire up the routes:
+
+```javascript
+import { loadRouteConfig, registerRoutes } from 'adapt-authoring-server'
+
+async init () {
+  const [auth, server] = await this.app.waitForModule('auth', 'server')
+  const config = await loadRouteConfig(this.rootDir, this)
+  const router = server.api.createChildRouter(config.root)
+  registerRoutes(router, config.routes, auth)
+}
+```
+
+### Route properties
+
+| Property | Required | Description |
+| -------- | -------- | ----------- |
+| `route` | Yes | Express-style route path (e.g. `"/reset/:id"`) |
+| `handlers` | Yes | Object mapping HTTP methods to handler method names on the module |
+| `permissions` | No | Object mapping HTTP methods to scope arrays (secured) or `null` (unsecured) |
+| `meta` | No | Object mapping HTTP methods to OpenAPI operation metadata |
+| `internal` | No | When `true`, restricts the route to localhost |
+| `override` | No | When `true` and defaults are in use, merges this route onto the matching default route instead of adding a duplicate |
+
+Handler strings are resolved to bound methods on the module instance automatically.
 
 ## Extend the `AbstractApiModule` class
-If you're building a non-trivial API (particularly one that uses the database), we highly recommend that you use `AbstractApiModule` as a base, as this includes a lot of boilerplate code and helper functions to make handling HTTP requests much easier. See [this page](writing-an-api) for more info on using the `AbstractApiModule` class. 
+If you're building a non-trivial API (particularly one that uses the database), we highly recommend that you use `AbstractApiModule` as a base, as this includes a lot of boilerplate code and helper functions to make handling HTTP requests much easier. See [this page](writing-an-api) for more info on using the `AbstractApiModule` class.
 
 ## Use HTTP status codes
 This may go without saying, but please stick to standardised HTTP response codes; they state your intentions and make it nice and easy for other devs to work with and react to.
@@ -18,12 +79,12 @@ Using the helper function is as simple as:
 async myHandler(req, res, next) {
   try {
     // do some stuff
-  } catch() {
+  } catch (e) {
     res.sendError(e);
   }
 }
 ```
 
 See the Express.js documentation for information on the extra functions available:
-- [Request](https://expressjs.com/en/4x/api.html#req)
-- [Response](https://expressjs.com/en/4x/api.html#res)
+- [Request](https://expressjs.com/en/5x/api.html#req)
+- [Response](https://expressjs.com/en/5x/api.html#res)

package/index.js

@@ -2,5 +2,5 @@
  * HTTP server functionality using Express.js
  * @namespace server
  */
-export { addExistenceProps, cacheRouteConfig, generateRouterMap, getAllRoutes, mapHandler } from './lib/utils.js'
+export { addExistenceProps, cacheRouteConfig, generateRouterMap, getAllRoutes, loadRouteConfig, mapHandler, registerRoutes } from './lib/utils.js'
 export { default } from './lib/ServerModule.js'

package/lib/utils/loadRouteConfig.js

@@ -0,0 +1,91 @@
+import path from 'node:path'
+import { App, readJson } from 'adapt-authoring-core'
+
+/**
+ * Resolves handler strings in route definitions against a target object and handler aliases.
+ * @param {Array} routes Array of route definition objects
+ * @param {Object} target The object to resolve handler strings against
+ * @param {Object} aliases Map of handler string aliases to pre-resolved functions
+ * @return {Array} Routes with handler strings replaced by bound functions
+ */
+function resolveHandlers (routes, target, aliases) {
+  return routes.map(routeDef => {
+    const resolved = { ...routeDef }
+    if (routeDef.handlers) {
+      resolved.handlers = Object.fromEntries(
+        Object.entries(routeDef.handlers).map(([method, handlerStr]) => {
+          if (Object.hasOwn(aliases, handlerStr)) {
+            return [method, aliases[handlerStr]]
+          }
+          if (typeof target[handlerStr] !== 'function') {
+            throw new Error(`Cannot resolve handler '${handlerStr}': no such method on target`)
+          }
+          return [method, target[handlerStr].bind(target)]
+        })
+      )
+    }
+    return resolved
+  })
+}
+
+/**
+ * Reads and processes a routes.json file from a module's root directory,
+ * validating against the app's jsonschema module and resolving handler strings against a target object.
+ * @param {String} rootDir Path to the module root (where routes.json lives)
+ * @param {Object} target The object to resolve handler strings against
+ * @param {Object} [options] Optional configuration
+ * @param {String} [options.schema] Schema name to validate against (defaults to 'routes')
+ * @param {Object} [options.handlerAliases] Map of handler string aliases to pre-resolved functions
+ * @param {String} [options.defaults] Path to a default routes template JSON file. When provided and
+ *   routes.json is found, the template's routes are resolved and prepended to config.routes.
+ *   Custom routes with `override: true` are merged onto the matching default (by path) instead of
+ *   being appended as duplicates.
+ * @return {Promise<Object|null>} Parsed config with resolved handlers, or null if no routes.json
+ * @memberof server
+ */
+export async function loadRouteConfig (rootDir, target, options = {}) {
+  const filePath = path.join(rootDir, 'routes.json')
+  let config
+  try {
+    config = await readJson(filePath)
+  } catch (e) {
+    if (e.code === 'ENOENT') return null
+    throw e
+  }
+  const jsonschema = await App.instance.waitForModule('jsonschema')
+  const schema = await jsonschema.getSchema(options.schema || 'routes')
+  try {
+    schema.validate(config)
+  } catch (e) {
+    throw new Error(`Invalid routes.json at ${filePath}: ${e.data?.errors || e.message}`)
+  }
+  const aliases = options.handlerAliases || {}
+
+  // Resolve handler strings in routes.json routes
+  const customRoutes = Array.isArray(config.routes)
+    ? resolveHandlers(config.routes, target, aliases)
+    : []
+
+  // Prepend default routes from template if provided
+  if (options.defaults) {
+    const template = await readJson(options.defaults)
+    const defaultRoutes = resolveHandlers(template.routes || [], target, aliases)
+    // Apply override routes onto matching defaults
+    const overrides = new Map(
+      customRoutes.filter(r => r.override).map(r => [r.route, r])
+    )
+    const matched = new Set()
+    const mergedDefaults = defaultRoutes.map(d => {
+      const o = overrides.get(d.route)
+      if (!o) return d
+      matched.add(d.route)
+      const { override, ...rest } = o
+      return { ...d, ...rest, handlers: { ...d.handlers, ...rest.handlers } }
+    })
+    const remaining = customRoutes.filter(r => !r.override || !matched.has(r.route))
+    config.routes = [...mergedDefaults, ...remaining]
+  } else {
+    config.routes = customRoutes
+  }
+  return config
+}

package/lib/utils/registerRoutes.js

@@ -0,0 +1,20 @@
+/**
+ * Registers routes on a router and configures their permissions with auth.
+ * @param {Router} router The router to add routes to
+ * @param {Array} routes Array of route definition objects
+ * @param {Object} auth The auth module instance
+ * @memberof server
+ */
+export function registerRoutes (router, routes, auth) {
+  for (const r of routes) {
+    router.addRoute(r)
+    if (!r.permissions) continue
+    for (const [method, perms] of Object.entries(r.permissions)) {
+      if (perms) {
+        auth.secureRoute(`${router.path}${r.route}`, method, perms)
+      } else {
+        auth.unsecureRoute(`${router.path}${r.route}`, method)
+      }
+    }
+  }
+}

package/lib/utils.js

@@ -2,4 +2,6 @@ export { addExistenceProps } from './utils/addExistenceProps.js'
 export { cacheRouteConfig } from './utils/cacheRouteConfig.js'
 export { generateRouterMap } from './utils/generateRouterMap.js'
 export { getAllRoutes } from './utils/getAllRoutes.js'
+export { loadRouteConfig } from './utils/loadRouteConfig.js'
 export { mapHandler } from './utils/mapHandler.js'
+export { registerRoutes } from './utils/registerRoutes.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-server",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "description": "Provides an Express application routing and more",
   "homepage": "https://github.com/adapt-security/adapt-authoring-server",
   "license": "GPL-3.0",
@@ -18,6 +18,7 @@
   },
   "devDependencies": {
     "@semantic-release/git": "^10.0.1",
+    "adapt-schemas": "^1.1.0",
     "conventional-changelog-eslint": "^6.0.0",
     "semantic-release": "^25.0.2",
     "standard": "^17.1.0"

package/schema/routeitem.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$anchor": "routeitem",
+  "type": "object",
+  "properties": {
+    "route": {
+      "type": "string",
+      "description": "Express-style route path"
+    },
+    "handlers": {
+      "type": "object",
+      "description": "Keys are HTTP methods, values are handler name strings",
+      "propertyNames": { "enum": ["get", "post", "put", "patch", "delete"] },
+      "additionalProperties": { "type": "string" }
+    },
+    "internal": {
+      "type": "boolean",
+      "description": "Restrict route to localhost",
+      "default": false
+    },
+    "permissions": {
+      "type": "object",
+      "description": "Keys are HTTP methods, values are permission scope arrays or null for unsecured",
+      "propertyNames": { "enum": ["get", "post", "put", "patch", "delete"] },
+      "additionalProperties": {
+        "oneOf": [
+          { "type": "array", "items": { "type": "string" } },
+          { "type": "null" }
+        ]
+      }
+    },
+    "meta": {
+      "type": "object",
+      "description": "Keys are HTTP methods, values are OpenAPI operation objects",
+      "propertyNames": { "enum": ["get", "post", "put", "patch", "delete"] }
+    },
+    "override": {
+      "type": "boolean",
+      "description": "When true and a defaults template is in use, merges this route's properties onto the matching default route (by path) instead of adding a duplicate",
+      "default": false
+    }
+  },
+  "required": ["route", "handlers"]
+}

package/schema/routes.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$anchor": "routes",
+  "type": "object",
+  "properties": {
+    "root": {
+      "type": "string",
+      "description": "Router root path"
+    },
+    "routes": {
+      "type": "array",
+      "description": "Route definitions"
+    }
+  },
+  "required": ["root"]
+}

package/tests/data/routes.json

@@ -0,0 +1,19 @@
+{
+  "root": "content",
+  "routes": [
+    {
+      "route": "/insertrecursive",
+      "handlers": { "post": "insertRecursive" },
+      "internal": false,
+      "meta": {
+        "post": {
+          "summary": "Insert hierarchical content data"
+        }
+      }
+    },
+    {
+      "route": "/list",
+      "handlers": { "get": "listItems" }
+    }
+  ]
+}

package/tests/utils-loadRouteConfig.spec.js

@@ -0,0 +1,478 @@
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { writeFile, mkdir, rm } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Schemas } from 'adapt-schemas'
+import { App } from 'adapt-authoring-core'
+import { loadRouteConfig } from '../lib/utils.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const SCHEMA_DIR = path.resolve(__dirname, '../schema')
+const dataDir = path.join(__dirname, 'data')
+const tmpDir = path.join(__dirname, 'tmp')
+
+/** Shared schema registry backing the jsonschema module mock */
+let schemas
+
+/**
+ * Writes a JSON file and returns its path.
+ * @param {String} filePath Absolute path to write the JSON file
+ * @param {Object} data Data to serialize as JSON
+ * @return {Promise<String>} The file path
+ * @ignore
+ */
+async function writeJson (filePath, data) {
+  await writeFile(filePath, JSON.stringify(data))
+  return filePath
+}
+
+describe('loadRouteConfig()', () => {
+  before(async () => {
+    await mkdir(tmpDir, { recursive: true })
+
+    // Build shared schema registry with the server's base schemas, mirroring how
+    // adapt-authoring-jsonschema auto-discovers schema/ files from all dependencies at startup
+    schemas = new Schemas()
+    await schemas.init()
+    await schemas.registerSchema(path.join(SCHEMA_DIR, 'routes.schema.json'))
+    await schemas.registerSchema(path.join(SCHEMA_DIR, 'routeitem.schema.json'))
+
+    // Mock App.instance.waitForModule so loadRouteConfig can resolve 'jsonschema'
+    // without a running app instance
+    App.instance.waitForModule = async (modName) => {
+      if (modName === 'jsonschema') {
+        return { getSchema: (name) => schemas.getSchema(name) }
+      }
+      throw new Error(`Module '${modName}' not available in test environment`)
+    }
+
+    // App.init() runs in the background and fails in test context (no real modules),
+    // setting process.exitCode = 1. Wait for it to settle then reset exitCode.
+    await App.instance.onReady().catch(() => {})
+    process.exitCode = 0
+  })
+
+  after(async () => {
+    await rm(tmpDir, { recursive: true, force: true })
+  })
+
+  it('should return null when routes.json does not exist', async () => {
+    const result = await loadRouteConfig(path.join(__dirname, 'nonexistent'), {})
+    assert.equal(result, null)
+  })
+
+  it('should read and return config from routes.json', async () => {
+    const target = {
+      insertRecursive: () => {},
+      listItems: () => {}
+    }
+    const config = await loadRouteConfig(dataDir, target)
+
+    assert.ok(config !== null)
+    assert.equal(config.root, 'content')
+    assert.ok(Array.isArray(config.routes))
+    assert.equal(config.routes.length, 2)
+  })
+
+  it('should resolve handler strings to bound functions', async () => {
+    let called = false
+    const target = {
+      insertRecursive () { called = true },
+      listItems: () => {}
+    }
+    const config = await loadRouteConfig(dataDir, target)
+    const handler = config.routes[0].handlers.post
+
+    assert.equal(typeof handler, 'function')
+    handler()
+    assert.ok(called)
+  })
+
+  it('should preserve non-handler fields on route definitions', async () => {
+    const target = {
+      insertRecursive: () => {},
+      listItems: () => {}
+    }
+    const config = await loadRouteConfig(dataDir, target)
+    const route = config.routes[0]
+
+    assert.equal(route.route, '/insertrecursive')
+    assert.equal(route.internal, false)
+    assert.ok(route.meta)
+  })
+
+  it('should use handlerAliases when provided', async () => {
+    const aliasHandler = () => 'alias'
+    const target = { listItems: () => {} }
+    const config = await loadRouteConfig(dataDir, target, { handlerAliases: { insertRecursive: aliasHandler } })
+
+    assert.equal(config.routes[0].handlers.post, aliasHandler)
+  })
+
+  it('should throw a clear error for unresolvable handler strings', async () => {
+    const target = { listItems: () => {} } // missing insertRecursive
+    await assert.rejects(
+      () => loadRouteConfig(dataDir, target),
+      /Cannot resolve handler 'insertRecursive'/
+    )
+  })
+
+  it('should throw when routes.json fails schema validation (missing required root)', async () => {
+    const dir = path.join(tmpDir, 'no-root')
+    await mkdir(dir, { recursive: true })
+    await writeJson(path.join(dir, 'routes.json'), { routes: [] })
+    await assert.rejects(
+      () => loadRouteConfig(dir, {}),
+      /Invalid routes\.json.*must have required property 'root'/s
+    )
+  })
+
+  it('should throw when routes.json fails schema validation (wrong type for root)', async () => {
+    const dir = path.join(tmpDir, 'wrong-root-type')
+    await mkdir(dir, { recursive: true })
+    await writeJson(path.join(dir, 'routes.json'), { root: 42, routes: [] })
+    await assert.rejects(
+      () => loadRouteConfig(dir, {}),
+      /Invalid routes\.json.*must be string/s
+    )
+  })
+
+  it('should preserve consumer-specific top-level fields after validation', async () => {
+    // Consumer schema mirrors how apiroutes/authroutes extend the base via $merge
+    const schemaFile = await writeJson(path.join(tmpDir, 'withschema.schema.json'), {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      $anchor: 'withschema',
+      $merge: {
+        source: { $ref: 'routes' },
+        with: {
+          properties: { schemaName: { type: 'string' } },
+          required: ['schemaName']
+        }
+      }
+    })
+    await schemas.registerSchema(schemaFile)
+    try {
+      const dir = path.join(tmpDir, 'consumer-fields')
+      await mkdir(dir, { recursive: true })
+      await writeJson(path.join(dir, 'routes.json'), { root: 'content', schemaName: 'content', routes: [] })
+      const config = await loadRouteConfig(dir, {}, { schema: 'withschema' })
+      assert.equal(config.schemaName, 'content')
+    } finally {
+      schemas.deregisterSchema('withschema')
+    }
+  })
+
+  it('should validate route items via consumer schema using $merge', async () => {
+    // Note: real consumer schemas use items.$ref: 'routeitem' which is resolved by the
+    // jsonschema module at startup. In tests we inline the items constraint because AJV
+    // throws anchor conflicts when $ref targets an already-registered schema.
+    const schemaFile = await writeJson(path.join(tmpDir, 'strict-routes.schema.json'), {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      $anchor: 'strict-routes',
+      $merge: {
+        source: { $ref: 'routes' },
+        with: {
+          properties: {
+            routes: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  route: { type: 'string' },
+                  handlers: { type: 'object' }
+                },
+                required: ['route', 'handlers']
+              }
+            }
+          }
+        }
+      }
+    })
+    await schemas.registerSchema(schemaFile)
+    try {
+      const dir = path.join(tmpDir, 'missing-route-field')
+      await mkdir(dir, { recursive: true })
+      await writeJson(path.join(dir, 'routes.json'), {
+        root: 'test',
+        routes: [{ handlers: { get: 'myHandler' } }]
+      })
+      await assert.rejects(
+        () => loadRouteConfig(dir, {}, { schema: 'strict-routes' }),
+        /Invalid routes\.json.*must have required property 'route'/s
+      )
+    } finally {
+      schemas.deregisterSchema('strict-routes')
+    }
+  })
+
+  it('should use a consumer-provided schema for top-level validation', async () => {
+    const schemaFile = await writeJson(path.join(tmpDir, 'custom.schema.json'), {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      $anchor: 'custom',
+      $merge: {
+        source: { $ref: 'routes' },
+        with: {
+          properties: { schemaName: { type: 'string' } },
+          required: ['schemaName']
+        }
+      }
+    })
+    await schemas.registerSchema(schemaFile)
+    try {
+      const dir = path.join(tmpDir, 'missing-schemaname')
+      await mkdir(dir, { recursive: true })
+      await writeJson(path.join(dir, 'routes.json'), { root: 'test', routes: [] })
+      await assert.rejects(
+        () => loadRouteConfig(dir, {}, { schema: 'custom' }),
+        /Invalid routes\.json.*must have required property 'schemaName'/s
+      )
+    } finally {
+      schemas.deregisterSchema('custom')
+    }
+  })
+
+  describe('permissions field in route items', () => {
+    // Note: real consumer schemas use items.$ref: 'routeitem' which includes the permissions
+    // property. In tests we inline the constraint because AJV throws anchor conflicts when
+    // $ref targets an already-registered schema. The permissions definition here mirrors
+    // routeitem.schema.json to ensure the same validation behaviour.
+    const permSchema = {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      $anchor: 'perm-routes',
+      $merge: {
+        source: { $ref: 'routes' },
+        with: {
+          properties: {
+            routes: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  route: { type: 'string' },
+                  handlers: { type: 'object' },
+                  permissions: {
+                    type: 'object',
+                    propertyNames: { enum: ['get', 'post', 'put', 'patch', 'delete'] },
+                    additionalProperties: {
+                      oneOf: [
+                        { type: 'array', items: { type: 'string' } },
+                        { type: 'null' }
+                      ]
+                    }
+                  }
+                },
+                required: ['route', 'handlers']
+              }
+            }
+          }
+        }
+      }
+    }
+
+    before(async () => {
+      await schemas.registerSchema(await writeJson(path.join(tmpDir, 'perm-routes.schema.json'), permSchema))
+    })
+
+    after(() => schemas.deregisterSchema('perm-routes'))
+
+    it('should accept null permission values (unsecured routes)', async () => {
+      const dir = path.join(tmpDir, 'perms-null')
+      await mkdir(dir, { recursive: true })
+      await writeJson(path.join(dir, 'routes.json'), {
+        root: 'test',
+        routes: [{ route: '/test', handlers: { post: 'myHandler' }, permissions: { post: null } }]
+      })
+      const config = await loadRouteConfig(dir, { myHandler: () => {} }, { schema: 'perm-routes' })
+      assert.equal(config.routes[0].permissions.post, null)
+    })
+
+    it('should reject invalid HTTP method keys in permissions', async () => {
+      const dir = path.join(tmpDir, 'perms-invalid-key')
+      await mkdir(dir, { recursive: true })
+      await writeJson(path.join(dir, 'routes.json'), {
+        root: 'test',
+        routes: [{ route: '/test', handlers: { post: 'myHandler' }, permissions: { invalidMethod: null } }]
+      })
+      await assert.rejects(
+        () => loadRouteConfig(dir, { myHandler: () => {} }, { schema: 'perm-routes' }),
+        /Invalid routes\.json.*property name must be valid/s
+      )
+    })
+  })
+
+  describe('defaults option', () => {
+    it('should prepend default routes from template when defaults path is provided', async () => {
+      const dir = path.join(tmpDir, 'with-defaults')
+      await mkdir(dir, { recursive: true })
+      await writeJson(path.join(dir, 'routes.json'), {
+        root: 'test',
+        routes: [{ route: '/custom', handlers: { get: 'listItems' } }]
+      })
+      const defaultsPath = path.join(tmpDir, 'defaults.json')
+      await writeJson(defaultsPath, {
+        routes: [{ route: '/', handlers: { post: 'insertRecursive' } }]
+      })
+      const target = {
+        insertRecursive: () => {},
+        listItems: () => {}
+      }
+      const config = await loadRouteConfig(dir, target, { defaults: defaultsPath })
+      assert.equal(config.routes.length, 2)
+      assert.equal(config.routes[0].route, '/')
+      assert.equal(config.routes[1].route, '/custom')
+    })
+
+    it('should resolve handler strings in default routes using handlerAliases', async () => {
+      const dir = path.join(tmpDir, 'defaults-aliases')
+      await mkdir(dir, { recursive: true })
+      await writeJson(path.join(dir, 'routes.json'), { root: 'test', routes: [] })
+      const defaultsPath = path.join(tmpDir, 'defaults-aliases.json')
+      await writeJson(defaultsPath, {
+        routes: [{ route: '/', handlers: { post: 'myAlias' } }]
+      })
+      let called = false
+      const aliasHandler = () => { called = true }
+      const config = await loadRouteConfig(dir, {}, {
+        defaults: defaultsPath,
+        handlerAliases: { myAlias: aliasHandler }
+      })
+      assert.equal(typeof config.routes[0].handlers.post, 'function')
+      config.routes[0].handlers.post()
+      assert.ok(called)
+    })
+
+    it('should resolve handler strings in default routes against target methods', async () => {
+      const dir = path.join(tmpDir, 'defaults-target')
+      await mkdir(dir, { recursive: true })
+      await writeJson(path.join(dir, 'routes.json'), { root: 'test', routes: [] })
+      const defaultsPath = path.join(tmpDir, 'defaults-target.json')
+      await writeJson(defaultsPath, {
+        routes: [{ route: '/', handlers: { get: 'myMethod' } }]
+      })
+      let called = false
+      const target = { myMethod () { called = true } }
+      const config = await loadRouteConfig(dir, target, { defaults: defaultsPath })
+      config.routes[0].handlers.get()
+      assert.ok(called)
+    })
+
+    it('should not load defaults when routes.json does not exist', async () => {
+      const defaultsPath = path.join(tmpDir, 'unused-defaults.json')
+      await writeJson(defaultsPath, {
+        routes: [{ route: '/', handlers: { get: 'foo' } }]
+      })
+      const result = await loadRouteConfig(path.join(__dirname, 'nonexistent'), {}, { defaults: defaultsPath })
+      assert.equal(result, null)
+    })
+
+    it('should preserve non-handler fields on default route definitions', async () => {
+      const dir = path.join(tmpDir, 'defaults-fields')
+      await mkdir(dir, { recursive: true })
+      await writeJson(path.join(dir, 'routes.json'), { root: 'test', routes: [] })
+      const defaultsPath = path.join(tmpDir, 'defaults-fields.json')
+      await writeJson(defaultsPath, {
+        routes: [{
+          route: '/',
+          handlers: { post: 'myHandler' },
+          permissions: { post: null },
+          meta: { post: { summary: 'Test' } }
+        }]
+      })
+      const config = await loadRouteConfig(dir, { myHandler: () => {} }, { defaults: defaultsPath })
+      assert.equal(config.routes[0].permissions.post, null)
+      assert.equal(config.routes[0].meta.post.summary, 'Test')
+    })
+
+    it('should merge override route properties onto matching default route', async () => {
+      const dir = path.join(tmpDir, 'override-merge')
+      await mkdir(dir, { recursive: true })
+      await writeJson(path.join(dir, 'routes.json'), {
+        root: 'test',
+        routes: [{
+          route: '/',
+          override: true,
+          handlers: { post: 'myHandler' },
+          meta: { post: { summary: 'Overridden' } }
+        }]
+      })
+      const defaultsPath = path.join(tmpDir, 'override-defaults.json')
+      await writeJson(defaultsPath, {
+        routes: [{ route: '/', handlers: { post: 'myHandler' }, permissions: { post: null } }]
+      })
+      const config = await loadRouteConfig(dir, { myHandler: () => {} }, { defaults: defaultsPath })
+      assert.equal(config.routes.length, 1)
+      assert.equal(config.routes[0].route, '/')
+      assert.equal(config.routes[0].meta.post.summary, 'Overridden')
+      assert.equal(config.routes[0].permissions.post, null)
+    })
+
+    it('should keep default handler when override does not replace it', async () => {
+      const dir = path.join(tmpDir, 'override-keep-handler')
+      await mkdir(dir, { recursive: true })
+      await writeJson(path.join(dir, 'routes.json'), {
+        root: 'test',
+        routes: [{
+          route: '/',
+          override: true,
+          handlers: { post: 'myHandler' },
+          meta: { post: { summary: 'Added meta' } }
+        }]
+      })
+      const defaultsPath = path.join(tmpDir, 'override-keep-handler-defaults.json')
+      await writeJson(defaultsPath, {
+        routes: [{ route: '/', handlers: { post: 'defaultHandler' } }]
+      })
+      const target = {
+        myHandler: () => {},
+        defaultHandler () {}
+      }
+      const config = await loadRouteConfig(dir, target, { defaults: defaultsPath })
+      // override handler takes precedence
+      assert.equal(typeof config.routes[0].handlers.post, 'function')
+      assert.equal(config.routes[0].meta.post.summary, 'Added meta')
+    })
+
+    it('should not remove override route from results when no matching default exists', async () => {
+      const dir = path.join(tmpDir, 'override-no-match')
+      await mkdir(dir, { recursive: true })
+      await writeJson(path.join(dir, 'routes.json'), {
+        root: 'test',
+        routes: [{
+          route: '/nomatch',
+          override: true,
+          handlers: { get: 'myHandler' },
+          meta: { get: { summary: 'Orphan' } }
+        }]
+      })
+      const defaultsPath = path.join(tmpDir, 'override-no-match-defaults.json')
+      await writeJson(defaultsPath, {
+        routes: [{ route: '/', handlers: { post: 'myHandler' } }]
+      })
+      const config = await loadRouteConfig(dir, { myHandler: () => {} }, { defaults: defaultsPath })
+      assert.equal(config.routes.length, 2)
+      assert.equal(config.routes[0].route, '/')
+      assert.equal(config.routes[1].route, '/nomatch')
+    })
+
+    it('should strip the override flag from merged route', async () => {
+      const dir = path.join(tmpDir, 'override-strip-flag')
+      await mkdir(dir, { recursive: true })
+      await writeJson(path.join(dir, 'routes.json'), {
+        root: 'test',
+        routes: [{
+          route: '/',
+          override: true,
+          handlers: { post: 'myHandler' },
+          meta: { post: { summary: 'Test' } }
+        }]
+      })
+      const defaultsPath = path.join(tmpDir, 'override-strip-defaults.json')
+      await writeJson(defaultsPath, {
+        routes: [{ route: '/', handlers: { post: 'myHandler' } }]
+      })
+      const config = await loadRouteConfig(dir, { myHandler: () => {} }, { defaults: defaultsPath })
+      assert.equal(config.routes[0].override, undefined)
+    })
+  })
+})