json-rest-api 1.0.23 → 1.0.25

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

@@ -3,6 +3,10 @@ import { processRelationships } from '../lib/writing/relationship-processor.js'
 import { updateManyToManyRelationship, createPivotRecords } from '../lib/writing/many-to-many-manipulations.js'
 import { ERROR_SUBTYPES } from '../lib/querying-writing/knex-constants.js'
 import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
+import {
+  requireDocumentResourceId,
+  requireExistingResourceId
+} from '../lib/querying-writing/resource-id-normalization.js'
 import {
   setupCommonRequest,
   validateCompleteReplacePayload,
@@ -11,7 +15,8 @@ import {
   applyFieldSetters,
   validatePivotResource,
   handleRecordReturnAfterWrite,
-  handleWriteMethodError
+  handleWriteMethodError,
+  commitOwnedTransaction
 } from './common.js'
 
 /**
@@ -61,14 +66,37 @@ export default async function putMethod ({
       includeDepthLimit: vars.includeDepthLimit,
       sortableFields: vars.sortableFields
     })
+    const normalizedPathId = params.id === undefined
+      ? null
+      : requireExistingResourceId(params.id, {
+        scopeOptions,
+        vars,
+        scopeName
+      })
+
+    if (normalizedPathId && !context.inputRecord?.data?.id) {
+      context.inputRecord = {
+        ...context.inputRecord,
+        data: {
+          ...(context.inputRecord?.data || {}),
+          id: normalizedPathId
+        }
+      }
+    }
+
     context.inputRecord = validateRequestContractOrThrow(
       requestContracts.put,
       context.inputRecord,
       'PUT request body is invalid'
     )
-    if (params.id && String(params.id) !== String(context.inputRecord.data.id)) {
+    const normalizedBodyId = requireDocumentResourceId(context.inputRecord.data.id, {
+      scopeOptions,
+      vars
+    })
+
+    if (normalizedPathId && normalizedPathId !== normalizedBodyId) {
       throw new RestApiValidationError(
-        `ID mismatch. URL path ID '${params.id}' does not match request body ID '${context.inputRecord.data.id}'`,
+        `ID mismatch. URL path ID '${normalizedPathId}' does not match request body ID '${normalizedBodyId}'`,
         {
           fields: ['data.id'],
           violations: [{
@@ -79,7 +107,8 @@ export default async function putMethod ({
         }
       )
     }
-    context.id = params.id || context.inputRecord.data.id
+    context.inputRecord.data.id = normalizedBodyId
+    context.id = normalizedPathId || normalizedBodyId
 
     // Validate that user has read access to all related resources
     // This ensures users can only create relationships to resources they can access
@@ -246,7 +275,7 @@ export default async function putMethod ({
           }
         })
       } else if (relData.length > 0) {
-        await createPivotRecords(api, context.id, relDef, relData, context.transaction)
+        await createPivotRecords(api, context.id, relDef, relData, context.transaction, context)
       }
     }
 
@@ -264,11 +293,7 @@ export default async function putMethod ({
       log
     })
 
-    // Commit transaction if we created it
-    if (context.shouldCommit) {
-      await context.transaction.commit()
-      await runHooks('afterCommit')
-    }
+    await commitOwnedTransaction(context, runHooks)
 
     return ret
   } catch (error) {

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

@@ -1,5 +1,3 @@
-import { ValidationError } from 'hooked-api'
-
 /**
  * release
  * Runs the hook that tells plugins to release resources

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

@@ -21,12 +21,14 @@ 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'
 import { DEFAULT_QUERY_LIMIT, DEFAULT_MAX_QUERY_LIMIT, DEFAULT_INCLUDE_DEPTH_LIMIT } from './lib/querying-writing/knex-constants.js'
+import { normalizeReturnRecordSetting } from './lib/querying-writing/return-record-settings.js'
 
 import getRelatedMethod from './rest-api-plugin-methods/get-related.js'
 import postRelationshipMethod from './rest-api-plugin-methods/post-relationship.js'
 import getRelationshipMethod from './rest-api-plugin-methods/get-relationship.js'
 import patchRelationshipMethod from './rest-api-plugin-methods/patch-relationship.js'
 import deleteRelationshipMethod from './rest-api-plugin-methods/delete-relationship.js'
+import { defaultNormalizeResourceId } from './lib/querying-writing/resource-id-normalization.js'
 
 export const RestApiPlugin = {
   name: 'rest-api',
@@ -66,43 +68,15 @@ export const RestApiPlugin = {
       : true // Default true for better DX in programmatic API
 
     vars.idProperty = restApiOptions.idProperty || 'id'
-
-    // Return full record configuration for API and Transport
-    // Support values: 'no', 'minimal', 'full'
-    const normalizeReturnValue = (value, defaultValue) => {
-      if (['no', 'minimal', 'full'].includes(value)) return value
-      return defaultValue
-    }
-
-    const optionConfigs = [
-      {
-        propName: 'returnRecordApi',
-        defaultValue: 'full',
-      },
-      {
-        propName: 'returnRecordTransport',
-        defaultValue: 'no',
-      },
-    ]
-
-    for (const config of optionConfigs) {
-      const optionValue = restApiOptions[config.propName]
-      let processedValue
-
-      if (typeof optionValue === 'object' && optionValue !== null) {
-        processedValue = {
-          post: normalizeReturnValue(optionValue.post, config.defaultValue),
-          put: normalizeReturnValue(optionValue.put, config.defaultValue),
-          patch: normalizeReturnValue(optionValue.patch, config.defaultValue),
-        }
-      } else if (optionValue !== undefined) {
-        const normalized = normalizeReturnValue(optionValue, config.defaultValue)
-        processedValue = { post: normalized, put: normalized, patch: normalized }
-      } else {
-        processedValue = { post: config.defaultValue, put: config.defaultValue, patch: config.defaultValue }
-      }
-      vars[config.propName] = processedValue
-    }
+    vars.normalizeId = typeof restApiOptions.normalizeId === 'function'
+      ? restApiOptions.normalizeId
+      : defaultNormalizeResourceId
+
+    // Return record configuration for API and Transport.
+    // Preferred values are 'no', 'minimal', and 'full'; booleans are normalized
+    // for backwards compatibility.
+    vars.returnRecordApi = normalizeReturnRecordSetting(restApiOptions.returnRecordApi, 'full')
+    vars.returnRecordTransport = normalizeReturnRecordSetting(restApiOptions.returnRecordTransport, 'no')
 
     log.debug('returnRecordApi configuration:', vars.returnRecordApi)
     log.debug('returnRecordTransport configuration:', vars.returnRecordTransport)

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

@@ -1,8 +1,6 @@
 import {
   calculatePosition,
   getInitialPosition,
-  isValidPosition,
-  assignInitialPositions,
 } from './lib/fractional-positioning.js'
 import { createStorageAdapter } from './lib/storage/storage-adapter.js'
 
@@ -167,7 +165,7 @@ export const PositioningPlugin = {
           fieldExists = true
         } else {
           // Check if it's a relationship name (as property)
-          for (const [fieldName, fieldDef] of Object.entries(schema)) {
+          for (const [, fieldDef] of Object.entries(schema)) {
             if (fieldDef.as === filterField) {
               fieldExists = true
               break
@@ -419,7 +417,6 @@ export const PositioningPlugin = {
       log.debug('*** Position filter conditions', { scopeName, filterConditions })
 
       // Query existing items in the same position group
-      const knex = api.knex.instance
       const tableName = adapter.getTableName()
       const idProperty = schemaInfo.idProperty
       const idColumn = adapter.getIdColumn()

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

@@ -0,0 +1,157 @@
+import { createStorageAdapterUtilities } from './lib/querying/storage-adapter-utils.js'
+
+const INLINE_POLICY_NAME = '<inline>'
+
+function createRowPolicyError (message, code = 'REST_API_ROW_POLICY_CONTRACT') {
+  const error = new Error(message)
+  error.code = code
+  return error
+}
+
+function compileRowPolicy ({ scopeName, scopeOptions = {}, policies }) {
+  const definition = scopeOptions.rowPolicy
+
+  if (definition === undefined || definition === null || definition === false) {
+    return null
+  }
+
+  if (typeof definition === 'function') {
+    return {
+      name: INLINE_POLICY_NAME,
+      source: 'inline',
+      applyQuery: definition
+    }
+  }
+
+  if (typeof definition === 'string') {
+    const name = definition.trim()
+    const applyQuery = policies[name]
+
+    if (!name || !applyQuery) {
+      throw createRowPolicyError(
+        `Unknown row policy '${definition}' on resource '${scopeName}'.`
+      )
+    }
+
+    return {
+      name,
+      source: 'registry',
+      applyQuery
+    }
+  }
+
+  throw createRowPolicyError(
+    `Row policy for resource '${scopeName}' must be a registered policy name, a function, or false.`
+  )
+}
+
+export const RowPolicyPlugin = {
+  name: 'row-policy',
+  dependencies: ['rest-api', 'rest-api-knex|rest-api-anyapi-knex'],
+
+  install ({ api, addHook, vars, helpers, log, scopes, pluginOptions = {} }) {
+    if (!api.knex?.instance) {
+      throw new Error('RowPolicyPlugin requires a storage plugin with knex support (rest-api-knex or rest-api-anyapi-knex).')
+    }
+
+    const policies = { ...(pluginOptions.policies || {}) }
+    for (const [name, policy] of Object.entries(policies)) {
+      if (typeof policy !== 'function') {
+        throw createRowPolicyError(`Row policy '${name}' must be a function.`)
+      }
+    }
+
+    vars.rowPolicy = {
+      policies: Object.keys(policies)
+    }
+
+    addHook('scope:added', 'compile-row-policy', {}, ({ context }) => {
+      const { scopeName, scopeOptions = {} } = context
+      const scope = scopes[scopeName]
+
+      scope.vars.rowPolicy = compileRowPolicy({
+        scopeName,
+        scopeOptions,
+        policies
+      })
+    })
+
+    addHook('knexQueryFiltering', 'apply-row-policy', {}, async (hookParams) => {
+      const { context } = hookParams
+      const {
+        query,
+        scopeName,
+        tableName,
+        db,
+        queryPurpose = 'unspecified',
+        isAnyApi = false,
+        storageAdapter: hookStorageAdapter
+      } = context.knexQuery || {}
+
+      if (!query || !scopeName) return
+
+      const compiledPolicy = scopes[scopeName]?.vars?.rowPolicy
+      if (!compiledPolicy) return
+
+      const adapterUtils = createStorageAdapterUtilities(hookParams, {
+        getStorageAdapter: helpers.getStorageAdapter
+      })
+      const storageAdapter = hookStorageAdapter || adapterUtils.fetchStorageAdapter(scopeName)
+
+      const column = (field, options = {}) => {
+        const targetScopeName = options.scopeName || scopeName
+        const alias = Object.prototype.hasOwnProperty.call(options, 'alias')
+          ? options.alias
+          : adapterUtils.defaultAliasForScope(targetScopeName)
+        return adapterUtils.translateColumn(targetScopeName, field, alias)
+      }
+
+      const value = (field, rawValue, options = {}) => {
+        const targetScopeName = options.scopeName || scopeName
+        return adapterUtils.translateFilterValue(targetScopeName, field, rawValue)
+      }
+
+      const result = await compiledPolicy.applyQuery({
+        query,
+        context,
+        scopeName,
+        tableName,
+        queryPurpose,
+        db,
+        isAnyApi,
+        storageAdapter,
+        column,
+        value,
+        api
+      })
+
+      if (result === false) {
+        query.whereRaw('1 = 0')
+      } else if (result !== true) {
+        throw createRowPolicyError(
+          `Row policy '${compiledPolicy.name}' on resource '${scopeName}' must return true after applying its predicate, or false to deny all rows.`
+        )
+      }
+    })
+
+    api.rowPolicies = {
+      getConfig: () => ({
+        policies: Object.keys(policies)
+      }),
+
+      getScopeConfig: (scopeName) => {
+        const compiledPolicy = scopes[scopeName]?.vars?.rowPolicy
+        if (!compiledPolicy) return null
+
+        return {
+          policy: compiledPolicy.name,
+          source: compiledPolicy.source
+        }
+      }
+    }
+
+    log.info('Row policy plugin installed', {
+      policies: Object.keys(policies)
+    })
+  }
+}

package/plugins/core/socketio-plugin.js

@@ -393,7 +393,6 @@ export const SocketIOPlugin = {
     let io
 
     api.startSocketServer = async (server, startOptions = {}) => {
-      const transportConfig = { ...config.transport, ...startOptions.transport }
       const authConfig = { ...config.auth, ...(startOptions.auth || {}) }
       const redisConfig = startOptions.redis ?? pluginOptions.redis ?? null
 

package/plugins/storage/local-storage.js

@@ -19,6 +19,45 @@ export class LocalStorage {
     this.maxFilenameLength = options.maxFilenameLength || 255
   }
 
+  hasPathSegments (filename) {
+    return filename.includes('/') ||
+      filename.includes('\\') ||
+      path.isAbsolute(filename) ||
+      path.win32.isAbsolute(filename) ||
+      /^[A-Za-z]:/.test(filename)
+  }
+
+  validateCustomBasename (basename) {
+    if (typeof basename !== 'string') {
+      throw new Error('Custom nameGenerator must return a string')
+    }
+    if (basename.trim().length === 0) {
+      throw new Error('Custom nameGenerator must return a non-empty basename')
+    }
+    if (this.hasPathSegments(basename)) {
+      throw new Error('Custom nameGenerator must return a basename, not a path')
+    }
+    return basename
+  }
+
+  resolveStoragePath (filename) {
+    if (typeof filename !== 'string' || filename.trim().length === 0) {
+      throw new Error('Invalid file name')
+    }
+    if (this.hasPathSegments(filename)) {
+      throw new Error('Invalid file path')
+    }
+
+    const resolvedDir = path.resolve(this.directory)
+    const resolvedPath = path.resolve(resolvedDir, filename)
+    const relative = path.relative(resolvedDir, resolvedPath)
+    if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+      throw new Error('Invalid file path')
+    }
+
+    return resolvedPath
+  }
+
   /**
    * Generate a safe filename
    */
@@ -61,7 +100,7 @@ export class LocalStorage {
         if (!this.nameGenerator) {
           throw new Error('nameGenerator function required for custom strategy')
         }
-        basename = await this.nameGenerator(file)
+        basename = this.validateCustomBasename(await this.nameGenerator(file))
         break
 
       default:
@@ -92,7 +131,7 @@ export class LocalStorage {
     return filename
       // Remove path traversal attempts
       .replace(/\.\./g, '')
-      .replace(/[\/\\]/g, '')
+      .replace(/[/\\]/g, '')
       // Remove control characters and special chars
       .replace(/[^\w\s.-]/g, '_')
       // Remove leading/trailing dots and spaces
@@ -107,7 +146,7 @@ export class LocalStorage {
    * Ensure filename is unique
    */
   async ensureUnique (filename) {
-    const filepath = path.join(this.directory, filename)
+    const filepath = this.resolveStoragePath(filename)
 
     try {
       await fs.access(filepath)
@@ -120,7 +159,7 @@ export class LocalStorage {
       do {
         newFilename = `${base}_${counter}${ext}`
         counter++
-      } while (await this.fileExists(path.join(this.directory, newFilename)))
+      } while (await this.fileExists(this.resolveStoragePath(newFilename)))
 
       return newFilename
     } catch (error) {
@@ -171,14 +210,7 @@ export class LocalStorage {
 
     // Generate secure filename
     const filename = await this.generateFilename(file)
-    const filepath = path.join(this.directory, filename)
-
-    // Ensure we're not writing outside our directory (defense in depth)
-    const resolvedPath = path.resolve(filepath)
-    const resolvedDir = path.resolve(this.directory)
-    if (!resolvedPath.startsWith(resolvedDir)) {
-      throw new Error('Invalid file path')
-    }
+    const filepath = this.resolveStoragePath(filename)
 
     // Write file
     if (file.data) {
@@ -198,14 +230,7 @@ export class LocalStorage {
    */
   async delete (url) {
     const filename = path.basename(url)
-    const filepath = path.join(this.directory, filename)
-
-    // Security check
-    const resolvedPath = path.resolve(filepath)
-    const resolvedDir = path.resolve(this.directory)
-    if (!resolvedPath.startsWith(resolvedDir)) {
-      throw new Error('Invalid file path')
-    }
+    const filepath = this.resolveStoragePath(filename)
 
     try {
       await fs.unlink(filepath)

package/plugins/storage/s3-storage.js

@@ -1,18 +1,17 @@
 /**
- * S3 Storage Adapter
+ * S3 Storage Adapter (mock/demo)
  *
- * Stores uploaded files in Amazon S3 or S3-compatible storage.
+ * Generates S3-style URLs without uploading files to Amazon S3.
  *
  * Usage:
  * ```javascript
- * import { S3Storage } from 'jsonrestapi/lib/storage/s3-storage.js';
+ * import { S3Storage } from 'json-rest-api';
  *
  * const storage = new S3Storage({
  *   bucket: 'my-uploads',
  *   region: 'us-east-1',
- *   accessKeyId: process.env.AWS_ACCESS_KEY_ID,
- *   secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
- *   prefix: 'uploads/' // optional path prefix
+ *   prefix: 'uploads/',
+ *   mockMode: true
  * });
  *
  * const schema = {
@@ -24,6 +23,12 @@
 import crypto from 'crypto'
 import path from 'path'
 
+const REAL_S3_NOT_IMPLEMENTED_MESSAGE = 'S3Storage real S3 mode is not implemented. The included adapter only supports mockMode: true; provide a production storage adapter or add an AWS SDK-backed implementation.'
+
+function createRealS3NotImplementedError () {
+  return new Error(REAL_S3_NOT_IMPLEMENTED_MESSAGE)
+}
+
 export class S3Storage {
   constructor (options = {}) {
     this.bucket = options.bucket
@@ -35,19 +40,15 @@ export class S3Storage {
       throw new Error('S3Storage requires a bucket name')
     }
 
-    // Note: In a real implementation, you would initialize the AWS SDK here
-    // For this example, we'll just mock the behavior
     this.mockMode = options.mockMode !== false // Default to mock mode
 
     if (!this.mockMode) {
-      // Real S3 initialization would go here
-      // const { S3Client } = require('@aws-sdk/client-s3');
-      // this.s3 = new S3Client({ region: this.region });
+      throw createRealS3NotImplementedError()
     }
   }
 
   /**
-   * Upload a file to S3
+   * Upload a file to mock S3 storage.
    * @param {Object} file - File object from detector
    * @returns {Promise<string>} URL of the uploaded file
    */
@@ -67,58 +68,26 @@ export class S3Storage {
       return url
     }
 
-    // Real S3 upload would go here
-    /*
-    const { PutObjectCommand } = require('@aws-sdk/client-s3');
-
-    const command = new PutObjectCommand({
-      Bucket: this.bucket,
-      Key: key,
-      Body: file.data,
-      ContentType: file.mimetype,
-      ACL: this.acl,
-      Metadata: {
-        originalName: file.filename
-      }
-    });
-
-    await this.s3.send(command);
-
-    // Return public URL
-    if (this.acl === 'public-read') {
-      return `https://${this.bucket}.s3.${this.region}.amazonaws.com/${key}`;
-    } else {
-      // For private files, you might return a signed URL
-      return await this.getSignedUrl(key);
-    }
-    */
+    throw createRealS3NotImplementedError()
   }
 
   /**
-   * Delete a file from S3
+   * Delete a file from mock S3 storage.
    * @param {string} url - URL returned by upload()
    * @returns {Promise<void>}
    */
   async delete (url) {
-    // Extract key from URL
-    const urlObj = new URL(url)
-    const key = urlObj.pathname.substring(1) // Remove leading /
-
-    if (this.mockMode) {
-      // Mock mode - just simulate deletion
-      await new Promise(resolve => setTimeout(resolve, 50))
+    if (!this.mockMode) {
+      throw createRealS3NotImplementedError()
     }
 
-    // Real S3 delete would go here
-    /*
-    const { DeleteObjectCommand } = require('@aws-sdk/client-s3');
+    const urlObj = new URL(url)
 
-    const command = new DeleteObjectCommand({
-      Bucket: this.bucket,
-      Key: key
-    });
+    if (urlObj.pathname.length === 0) {
+      throw new Error('Invalid S3 object URL')
+    }
 
-    await this.s3.send(command);
-    */
+    // Mock mode - just simulate deletion
+    await new Promise(resolve => setTimeout(resolve, 50))
   }
 }

package/quickTest.js

@@ -70,6 +70,7 @@ const harperResult = await api.resources.publishers.post({
     name: 'HarperCollins'
   }
 })
+console.log('Created second publisher:', inspect(harperResult))
 
 // Method 3: Full JSON:API mode (standards compliant)
 const oxfordResult = await api.resources.publishers.post({