json-rest-api 1.0.24 → 1.0.26

package/plugins/core/rest-api-plugin-methods/patch-relationship.js

@@ -1,4 +1,8 @@
-import { handleWriteMethodError } from './common.js'
+import {
+  commitOwnedTransaction,
+  handleWriteMethodError,
+  validateRelationshipRoutePayload
+} from './common.js'
 import { requireExistingResourceId } from '../lib/querying-writing/resource-id-normalization.js'
 
 /**
@@ -19,6 +23,7 @@ export default async function patchRelationshipMethod ({ params, context, vars,
     scopeName
   })
   context.relationshipName = params.relationshipName
+  context.schemaInfo = scopes[scopeName].vars.schemaInfo
 
   // Transaction handling
   context.transaction = params.transaction ||
@@ -31,6 +36,14 @@ export default async function patchRelationshipMethod ({ params, context, vars,
     await runHooks('checkPermissions')
     await runHooks('checkPermissionsPatchRelationship')
 
+    const relationshipData = validateRelationshipRoutePayload({
+      context,
+      vars,
+      scopeName,
+      operation: 'patchRelationship',
+      relationshipData: params.relationshipData
+    })
+
     // Reuse existing patch with relationship data
     await scope.patch({
       id: context.id,
@@ -39,21 +52,19 @@ export default async function patchRelationshipMethod ({ params, context, vars,
           type: scopeName,
           id: context.id,
           relationships: {
-            [params.relationshipName]: { data: params.relationshipData }
+            [params.relationshipName]: { data: relationshipData }
           }
         }
       },
       transaction: context.transaction,
       simplified: false,
       isTransport: params.isTransport
-    })
+    }, { ...context })
 
     await runHooks('finish')
     await runHooks('finishPatchRelationship')
 
-    if (context.shouldCommit) {
-      await context.transaction.commit()
-    }
+    await commitOwnedTransaction(context, runHooks)
 
     // 204 No Content
   } catch (error) {

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

@@ -14,7 +14,8 @@ import {
   applyFieldSetters,
   validatePivotResource,
   handleRecordReturnAfterWrite,
-  handleWriteMethodError
+  handleWriteMethodError,
+  commitOwnedTransaction
 } from './common.js'
 
 /**
@@ -222,11 +223,7 @@ export default async function patchMethod ({
       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/post-relationship.js

@@ -1,5 +1,11 @@
-import { RestApiResourceError, RestApiValidationError, RestApiPayloadError } from '../../../lib/rest-api-errors.js'
-import { findRelationshipDefinition, handleWriteMethodError } from './common.js'
+import { RestApiResourceError, RestApiValidationError } from '../../../lib/rest-api-errors.js'
+import {
+  commitOwnedTransaction,
+  findRelationshipDefinition,
+  getVisibleRelationshipParent,
+  handleWriteMethodError,
+  validateRelationshipRoutePayload
+} from './common.js'
 import { createPivotRecords } from '../lib/writing/many-to-many-manipulations.js'
 import {
   normalizeRelationshipIdentifiers,
@@ -50,22 +56,28 @@ export default async function postRelationshipMethod ({ params, context, vars, h
       )
     }
 
-    if (!Array.isArray(params.relationshipData)) {
-      throw new RestApiPayloadError('POST to relationship requires array of resource identifiers')
-    }
+    params.relationshipData = validateRelationshipRoutePayload({
+      context,
+      vars,
+      scopeName,
+      operation: 'postRelationship',
+      relationshipData: params.relationshipData
+    })
     params.relationshipData = normalizeRelationshipIdentifiers(params.relationshipData, { api })
 
     // Check permissions
     await runHooks('checkPermissions')
     await runHooks('checkPermissionsPostRelationship')
 
-    // Verify parent exists
-    const exists = await helpers.dataExists({
+    // Verify the parent exists in the caller's visible dataset.
+    const parentRecord = await getVisibleRelationshipParent({
+      context,
+      helpers,
       scopeName,
-      context: { db: context.db, id: context.id, schemaInfo: context.schemaInfo },
+      runHooks
     })
 
-    if (!exists) {
+    if (!parentRecord) {
       throw new RestApiResourceError('Resource not found', { subtype: 'not_found' })
     }
 
@@ -84,7 +96,7 @@ export default async function postRelationshipMethod ({ params, context, vars, h
           through: relDef.through,
           foreignKey: relDef.foreignKey,
           otherKey: relDef.otherKey
-        }, params.relationshipData, context.transaction)
+        }, params.relationshipData, context.transaction, context)
       }
     } else if (relDef.type === 'hasMany') {
       // Update foreign keys for hasMany
@@ -101,16 +113,14 @@ export default async function postRelationshipMethod ({ params, context, vars, h
           },
           transaction: context.transaction,
           simplified: false
-        })
+        }, { ...context })
       }
     }
 
     await runHooks('finish')
     await runHooks('finishPostRelationship')
 
-    if (context.shouldCommit) {
-      await context.transaction.commit()
-    }
+    await commitOwnedTransaction(context, runHooks)
 
     // 204 No Content
   } catch (error) {

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

@@ -9,7 +9,8 @@ import {
   applyFieldSetters,
   validatePivotResource,
   handleRecordReturnAfterWrite,
-  handleWriteMethodError
+  handleWriteMethodError,
+  commitOwnedTransaction
 } from './common.js'
 
 /**
@@ -151,7 +152,7 @@ export default async function postMethod ({
 
       // Validate pivot resource exists
       validatePivotResource(scopes, relDef, relName)
-      await createPivotRecords(api, context.id, relDef, relData, context.transaction)
+      await createPivotRecords(api, context.id, relDef, relData, context.transaction, context)
     }
 
     const ret = await handleRecordReturnAfterWrite({
@@ -168,11 +169,7 @@ export default async function postMethod ({
       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/put.js

@@ -15,7 +15,8 @@ import {
   applyFieldSetters,
   validatePivotResource,
   handleRecordReturnAfterWrite,
-  handleWriteMethodError
+  handleWriteMethodError,
+  commitOwnedTransaction
 } from './common.js'
 
 /**
@@ -274,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)
       }
     }
 
@@ -292,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.js

@@ -21,6 +21,7 @@ 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'
@@ -71,42 +72,11 @@ export const RestApiPlugin = {
       ? restApiOptions.normalizeId
       : defaultNormalizeResourceId
 
-    // 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
-    }
+    // 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-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/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:
@@ -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,61 +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) {
-    const urlObj = new URL(url)
-
-    if (this.mockMode) {
-      // Mock mode - just simulate deletion
-      await new Promise(resolve => setTimeout(resolve, 50))
-      return
+    if (!this.mockMode) {
+      throw createRealS3NotImplementedError()
     }
 
+    const urlObj = new URL(url)
+
     if (urlObj.pathname.length === 0) {
       throw new Error('Invalid S3 object URL')
     }
 
-    // Real S3 delete would go here
-    /*
-    const { DeleteObjectCommand } = require('@aws-sdk/client-s3');
-
-    const command = new DeleteObjectCommand({
-      Bucket: this.bucket,
-      Key: key
-    });
-
-    await this.s3.send(command);
-    */
+    // Mock mode - just simulate deletion
+    await new Promise(resolve => setTimeout(resolve, 50))
   }
 }

package/tests/README.md

@@ -20,7 +20,7 @@ All tests MUST use `simplified: false` to ensure JSON:API compliance:
 const result = await api.resources.resourceName.method({
   inputRecord: jsonApiDocument,
   simplified: false,
-  returnFullRecord: true/false  // Based on needs
+  returnFullRecord: 'full' // Use 'no', 'minimal', or 'full' based on needs
 });
 ```