json-rest-api 1.0.22 → 1.0.23

package/plugins/core/rest-api-plugin-methods/query.js

@@ -1,8 +1,8 @@
-import { RestApiValidationError } from '../../../lib/rest-api-errors.js'
-import { validateQueryPayload } from '../lib/querying-writing/payload-validators.js'
 import { normalizeRecordAttributes } from '../lib/querying-writing/database-value-normalizers.js'
 import { getRequestedComputedFields } from '../lib/querying-writing/knex-field-helpers.js'
+import { getEffectiveSortableFields } from '../lib/querying/query-field-sort-helpers.js'
 import { transformJsonApiToSimplified } from '../lib/querying-writing/simplified-helpers.js'
+import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
 import { cascadeConfig } from './common.js'
 
 /**
@@ -61,66 +61,28 @@ export default async function queryMethod ({
   context.scopeName = scopeName
 
   // These are just shortcuts used in this function and will be returned
-  const searchSchema = context.schemaInfo.searchSchemaInstance
   const schemaStructure = context.schemaInfo.schemaInstance.structure
   const schemaRelationships = context.schemaInfo.schemaRelationships
 
   // Sortable fields and sort (mab)
-  context.sortableFields = vars.sortableFields
+  context.sortableFields = getEffectiveSortableFields(vars)
   // Apply default sort if no sort specified
   if (context.queryParams.sort.length === 0 && vars.defaultSort) {
     context.queryParams.sort = Array.isArray(vars.defaultSort) ? vars.defaultSort : [vars.defaultSort]
   }
 
-  // Validate query parameters to ensure they follow JSON:API specification and security rules.
-  // This checks that filters are valid field names, sort fields exist in sortableFields array
-  // (preventing SQL injection), pagination uses valid page[size]/page[number] format, and include
-  // paths reference real relationships. Example: sort: ['-createdAt', 'title'] is checked against
-  // sortableFields to ensure users can't sort by sensitive fields like 'password_hash'.
-  validateQueryPayload({ queryParams: context.queryParams }, context.sortableFields, vars.includeDepthLimit)
-
-  // Validate search/filter parameters against searchSchema
-  if (context.queryParams.filters && Object.keys(context.queryParams.filters).length > 0) {
-    // Only allow filtering if searchSchema is defined
-    if (!searchSchema) {
-      throw new RestApiValidationError(
-        `Filtering is not enabled for resource '${scopeName}'. To enable filtering, add 'search: true' to schema fields or define a searchSchema.`,
-        {
-          fields: Object.keys(context.queryParams.filters).map(field => `filters.${field}`),
-          violations: [{
-            field: 'filters',
-            rule: 'filtering_not_enabled',
-            message: 'Resource does not have searchable fields defined'
-          }]
-        }
-      )
-    }
-
-    // Validate the filter parameters searchSchema
-    const { validatedObject, errors } = await searchSchema.validate(context.queryParams.filters, {
-      onlyObjectValues: true // Partial validation for filters
-    })
-
-    // If there are validation errors, throw an error
-    if (Object.keys(errors).length > 0) {
-      const violations = Object.entries(errors).map(([field, error]) => ({
-        field: `filters.${field}`,
-        rule: error.code || 'invalid_value',
-        message: error.message
-      }))
-
-      throw new RestApiValidationError(
-        'Invalid filter parameters',
-        {
-          fields: Object.keys(errors).map(field => `filters.${field}`),
-          violations
-        }
-      )
-    }
-
-    // Replace filter with validated/transformed values
-    context.queryParams.filters = validatedObject
-  }
+  const requestContracts = getRequestContracts({
+    scopeName,
+    schemaInfo: context.schemaInfo,
+    includeDepthLimit: vars.includeDepthLimit,
+    sortableFields: context.sortableFields
+  })
+  const validatedRequest = validateRequestContractOrThrow(
+    requestContracts.query,
+    { queryParams: context.queryParams },
+    'Query parameters are invalid'
+  )
+  context.queryParams = validatedRequest.queryParams || {}
 
   // Centralised checkPermissions function
   await scope.checkPermissions({

package/plugins/core/rest-api-plugin.js

@@ -16,6 +16,7 @@ import patchMethod from './rest-api-plugin-methods/patch.js'
 import deleteMethod from './rest-api-plugin-methods/delete.js'
 import enrichAttributesMethod from './rest-api-plugin-methods/enrich-attributes.js'
 import checkPermissionsMethod from './rest-api-plugin-methods/check-permissions.js'
+import applyQueryFiltersMethod from './rest-api-plugin-methods/apply-query-filters.js'
 import addRouteMethod from './rest-api-plugin-methods/add-route.js'
 import releaseMethod from './rest-api-plugin-methods/release.js'
 import { defaultDataHelpers } from './lib/querying-writing/default-data-helpers.js'
@@ -148,6 +149,7 @@ export const RestApiPlugin = {
     // Non-URL methods
     addScopeMethod('enrichAttributes', enrichAttributesMethod)
     addScopeMethod('checkPermissions', checkPermissionsMethod)
+    addScopeMethod('applyQueryFilters', applyQueryFiltersMethod)
 
     // *********
     // Helpers

package/plugins/core/rest-api-positioning-plugin.js

@@ -27,7 +27,7 @@ export const PositioningPlugin = {
     // Get configuration - hooked-api namespaces options by plugin name
     const positioningOptions = pluginOptions || {}
 
-    // Store configuration in vars (data only) - inspired by multihome pattern
+    // Store configuration in vars (data only) so hooks can use it without re-reading plugin options.
     vars.positioning = {
       field: positioningOptions.field || 'position',
       filters: positioningOptions.filters || [],

package/plugins/core/rest-api-query-projections-plugin.js

@@ -0,0 +1,130 @@
+export const QueryProjectionsPlugin = {
+  name: 'query-projections',
+  dependencies: ['rest-api'],
+
+  install ({ addHook, log }) {
+    const normalizeQueryFields = ({ scopeName, scopeOptions = {} }) => {
+      const schema = scopeOptions.schema || {}
+      const relationships = scopeOptions.relationships || {}
+      const rawQueryFields = scopeOptions.queryFields || {}
+      const normalized = {}
+      const reservedNames = new Set(Object.keys(schema))
+
+      if (!rawQueryFields || typeof rawQueryFields !== 'object' || Array.isArray(rawQueryFields)) {
+        throw new Error(`Invalid queryFields configuration for scope '${scopeName}'. Expected an object.`)
+      }
+
+      for (const relName of Object.keys(relationships)) {
+        reservedNames.add(relName)
+      }
+
+      for (const fieldDef of Object.values(schema)) {
+        if (fieldDef?.belongsTo && fieldDef?.as) {
+          reservedNames.add(fieldDef.as)
+        }
+      }
+
+      for (const [fieldName, fieldDef] of Object.entries(rawQueryFields)) {
+        if (!fieldDef || typeof fieldDef !== 'object' || Array.isArray(fieldDef)) {
+          throw new Error(`Query field '${fieldName}' in scope '${scopeName}' must be an object.`)
+        }
+
+        if (reservedNames.has(fieldName)) {
+          throw new Error(`Query field '${fieldName}' in scope '${scopeName}' conflicts with an existing schema or relationship name.`)
+        }
+
+        if (!fieldDef.type) {
+          throw new Error(`Query field '${fieldName}' in scope '${scopeName}' must have a type.`)
+        }
+
+        const select = fieldDef.select || fieldDef.project
+        if (typeof select !== 'function') {
+          throw new Error(`Query field '${fieldName}' in scope '${scopeName}' must define a select() function.`)
+        }
+
+        normalized[fieldName] = {
+          ...fieldDef,
+          select,
+          sortable: fieldDef.sortable === true,
+          hidden: fieldDef.hidden === true,
+          normallyHidden: fieldDef.normallyHidden === true
+        }
+      }
+
+      return normalized
+    }
+
+    const stripQueryFieldInput = ({ context, scopeName, scope, scopes }) => {
+      const inputAttributes = context?.inputRecord?.data?.attributes
+      const queryFields = scopes?.[scopeName]?.vars?.queryFields || scope?.vars?.queryFields || {}
+
+      if (!inputAttributes || typeof inputAttributes !== 'object' || Array.isArray(inputAttributes)) {
+        return
+      }
+
+      const stripped = []
+      for (const fieldName of Object.keys(queryFields)) {
+        if (Object.hasOwn(inputAttributes, fieldName)) {
+          delete inputAttributes[fieldName]
+          stripped.push(fieldName)
+        }
+      }
+
+      if (stripped.length > 0) {
+        const message = `Query fields [${stripped.join(', ')}] were sent in input for resource '${scopeName}' but will be ignored as they are query output only`
+        if (typeof log?.warn === 'function') {
+          log.warn(message)
+        } else {
+          console.warn(message)
+        }
+      }
+    }
+
+    const validateCompiledQueryFieldNamespace = ({ scopeName, scope, vars, scopes }) => {
+      const activeScope = scope || scopes?.[scopeName]
+      const scopeVars = vars || activeScope?.vars || {}
+      const queryFields = scopeVars.queryFields || {}
+      const schemaInfo = activeScope?.vars?.schemaInfo || scopeVars.schemaInfo || {}
+
+      if (Object.keys(queryFields).length === 0) {
+        return
+      }
+
+      const reservedNames = new Set([
+        ...Object.keys(schemaInfo.schemaStructure || {}),
+        ...Object.keys(schemaInfo.computed || {}),
+        ...Object.keys(schemaInfo.schemaRelationships || {})
+      ])
+
+      for (const fieldDef of Object.values(schemaInfo.schemaStructure || {})) {
+        if (fieldDef?.belongsTo && fieldDef?.as) {
+          reservedNames.add(fieldDef.as)
+        }
+      }
+
+      for (const fieldName of Object.keys(queryFields)) {
+        if (reservedNames.has(fieldName)) {
+          throw new Error(`Query field '${fieldName}' in scope '${scopeName}' conflicts with an existing schema, computed, or relationship name.`)
+        }
+      }
+    }
+
+    addHook('scope:added', 'compile-query-projections', { afterFunction: 'turnScopeInitIntoVars' }, ({ context, scopes }) => {
+      const scopeName = context.scopeName
+      const scope = scopes[scopeName]
+      const vars = scope?.vars || {}
+      const scopeOptions = scope?.scopeOptions || context.scopeOptions || {}
+      const queryFields = normalizeQueryFields({ scopeName, scopeOptions })
+
+      vars.queryFields = queryFields
+      validateCompiledQueryFieldNamespace({ scopeName, scope, vars, scopes })
+
+      log.debug(`Compiled query fields for '${scopeName}'`, {
+        queryFields: Object.keys(queryFields),
+        sortable: Object.keys(queryFields).filter((fieldName) => queryFields[fieldName].sortable === true)
+      })
+    })
+
+    addHook('beforeSchemaValidate', 'strip-query-field-input', {}, stripQueryFieldInput)
+  }
+}

package/plugins/core/socketio-plugin.js

@@ -206,9 +206,7 @@ async function registerSubscription ({
       }
     }
 
-    const { validatedObject, errors } = await searchSchemaInstance.validate(validatedFilters, {
-      onlyObjectValues: true
-    })
+    const { validatedObject, errors } = await searchSchemaInstance.patch(validatedFilters)
 
     if (errors && Object.keys(errors).length > 0) {
       const error = new Error('Invalid filter values')