json-rest-api 1.0.20 → 1.0.22

package/audit/evidence/code/critical-pass1/json-rest-api__plugins__core__file-handling-plugin.js.txt

@@ -0,0 +1,342 @@
+     1	/**
+     2	 * File Handling Plugin for JSON REST API
+     3	 *
+     4	 * This plugin provides automatic file upload handling based on schema definitions.
+     5	 * It works with any protocol connector (HTTP, Express, WebSocket, etc.) by using
+     6	 * a detector registry pattern.
+     7	 *
+     8	 * Features:
+     9	 * - Schema-driven: Detects file fields from type: 'file' in schemas
+    10	 * - Protocol-agnostic: Works with any connector that registers a detector
+    11	 * - Storage pluggable: Different fields can use different storage backends
+    12	 * - Zero configuration: Just define file fields in your schema
+    13	 *
+    14	 * Usage:
+    15	 * ```javascript
+    16	 * // 1. Define schema with file fields
+    17	 * const imageSchema = {
+    18	 *   title: { type: 'string' },
+    19	 *   uploadedImage: {
+    20	 *     type: 'file',
+    21	 *     storage: S3Storage,
+    22	 *     accepts: ['image/jpeg', 'image/png']
+    23	 *   }
+    24	 * };
+    25	 *
+    26	 * // 2. Use plugins (order matters - file-handling depends on rest-api)
+    27	 * api.use(RestApiPlugin);
+    28	 * api.use(FileHandlingPlugin);
+    29	 * api.use(ExpressPlugin); // Or any other connector
+    30	 *
+    31	 * // 3. Files are automatically handled!
+    32	 * ```
+    33	 */
+    34	
+    35	import { RestApiValidationError } from '../../lib/rest-api-errors.js'
+    36	
+    37	export const FileHandlingPlugin = {
+    38	  name: 'file-handling',
+    39	  dependencies: ['rest-api'],
+    40	
+    41	  install ({ addHook, helpers, scopes, log, vars, on, api }) {
+    42	    // Track which scopes have file fields
+    43	    const fileScopes = new Map() // scopeName -> fileField[]
+    44	
+    45	    // Registry of file detectors from various protocols
+    46	    const detectorRegistry = []
+    47	
+    48	    /**
+    49	     * Register a file detector from a protocol plugin
+    50	     *
+    51	     * @param {Object} detector - The detector object
+    52	     * @param {string} detector.name - Name of the detector (e.g., 'http-multipart')
+    53	     * @param {Function} detector.detect - Function to check if this detector applies
+    54	     * @param {Function} detector.parse - Function to parse files from the request
+    55	     */
+    56	    api.rest.registerFileDetector = (detector) => {
+    57	      if (!detector || !detector.name || !detector.detect || !detector.parse) {
+    58	        throw new Error('File detector must have name, detect(), and parse() properties')
+    59	      }
+    60	
+    61	      detectorRegistry.push(detector)
+    62	      log.debug(`Registered file detector: ${detector.name}`)
+    63	    }
+    64	
+    65	    // Store detectors array for inspection
+    66	    api.rest.fileDetectors = detectorRegistry
+    67	
+    68	    /**
+    69	     * Analyze a scope's schema to find file fields
+    70	     */
+    71	    const analyzeScopeSchema = (scopeName, scopeOptions) => {
+    72	      const schema = scopeOptions?.schema
+    73	      if (!schema) return
+    74	
+    75	      const fileFields = []
+    76	
+    77	      // Look for fields with type: 'file'
+    78	      for (const [fieldName, fieldConfig] of Object.entries(schema)) {
+    79	        if (fieldConfig && fieldConfig.type === 'file') {
+    80	          fileFields.push({
+    81	            field: fieldName,
+    82	            storage: fieldConfig.storage,
+    83	            accepts: fieldConfig.accepts || ['*'],
+    84	            maxSize: fieldConfig.maxSize,
+    85	            required: fieldConfig.required || false
+    86	          })
+    87	        }
+    88	      }
+    89	
+    90	      if (fileFields.length > 0) {
+    91	        fileScopes.set(scopeName, fileFields)
+    92	        log.info(`Scope '${scopeName}' has ${fileFields.length} file field(s): ${fileFields.map(f => f.field).join(', ')}`)
+    93	      }
+    94	    }
+    95	
+    96	    // Analyze existing scopes
+    97	    for (const [scopeName, scope] of Object.entries(scopes)) {
+    98	      if (scope._scopeOptions) {
+    99	        analyzeScopeSchema(scopeName, scope._scopeOptions)
+   100	      }
+   101	    }
+   102	
+   103	    // Listen for new scopes being added
+   104	    addHook('scope:added', 'analyzeFileFields', {}, ({ context }) => {
+   105	      const { scopeName, scopeOptions } = context
+   106	      analyzeScopeSchema(scopeName, scopeOptions)
+   107	    })
+   108	
+   109	    /**
+   110	     * Process files for a scope if it has file fields
+   111	     */
+   112	    const processFiles = async (scopeName, params, context) => {
+   113	      const fileFields = fileScopes.get(scopeName)
+   114	      if (!fileFields || fileFields.length === 0) {
+   115	        return // This scope doesn't have file fields
+   116	      }
+   117	
+   118	      // Try each detector to see if we have files
+   119	      let parsed = null
+   120	      let detectorUsed = null
+   121	
+   122	      for (const detector of detectorRegistry) {
+   123	        try {
+   124	          if (await detector.detect(params, context)) {
+   125	            log.debug(`Detector '${detector.name}' matched for scope '${scopeName}'`)
+   126	            parsed = await detector.parse(params, context)
+   127	            detectorUsed = detector.name
+   128	            break
+   129	          }
+   130	        } catch (error) {
+   131	          log.warn(`Detector '${detector.name}' failed:`, error)
+   132	        }
+   133	      }
+   134	
+   135	      if (!parsed) {
+   136	        // No files detected - check if any were required
+   137	        for (const fieldConfig of fileFields) {
+   138	          if (fieldConfig.required && !params.inputRecord?.data?.attributes?.[fieldConfig.field]) {
+   139	            throw new RestApiValidationError(
+   140	              `Required file field '${fieldConfig.field}' is missing`,
+   141	              {
+   142	                fields: [fieldConfig.field],
+   143	                violations: [{
+   144	                  field: fieldConfig.field,
+   145	                  message: 'This field is required'
+   146	                }]
+   147	              }
+   148	            )
+   149	          }
+   150	        }
+   151	        return
+   152	      }
+   153	
+   154	      log.debug(`Processing files with detector '${detectorUsed}'`)
+   155	      const { fields, files } = parsed
+   156	
+   157	      // Process each file field defined in schema
+   158	      for (const fieldConfig of fileFields) {
+   159	        const file = files[fieldConfig.field]
+   160	
+   161	        if (!file) {
+   162	          if (fieldConfig.required) {
+   163	            throw new RestApiValidationError(
+   164	              `Required file field '${fieldConfig.field}' is missing`,
+   165	              {
+   166	                fields: [fieldConfig.field],
+   167	                violations: [{
+   168	                  field: fieldConfig.field,
+   169	                  message: 'This field is required'
+   170	                }]
+   171	              }
+   172	            )
+   173	          }
+   174	          continue
+   175	        }
+   176	
+   177	        // Validate mime type
+   178	        if (fieldConfig.accepts[0] !== '*') {
+   179	          const acceptable = fieldConfig.accepts.some(pattern => {
+   180	            if (pattern.endsWith('/*')) {
+   181	              // e.g., 'image/*'
+   182	              const prefix = pattern.slice(0, -2)
+   183	              return file.mimetype.startsWith(prefix + '/')
+   184	            }
+   185	            return file.mimetype === pattern
+   186	          })
+   187	
+   188	          if (!acceptable) {
+   189	            throw new RestApiValidationError(
+   190	              `Invalid file type for field '${fieldConfig.field}'`,
+   191	              {
+   192	                fields: [fieldConfig.field],
+   193	                violations: [{
+   194	                  field: fieldConfig.field,
+   195	                  message: `Expected ${fieldConfig.accepts.join(' or ')}, got ${file.mimetype}`
+   196	                }]
+   197	              }
+   198	            )
+   199	          }
+   200	        }
+   201	
+   202	        // Validate file size
+   203	        if (fieldConfig.maxSize) {
+   204	          const maxBytes = parseSize(fieldConfig.maxSize)
+   205	          if (file.size > maxBytes) {
+   206	            throw new RestApiValidationError(
+   207	              `File too large for field '${fieldConfig.field}'`,
+   208	              {
+   209	                fields: [fieldConfig.field],
+   210	                violations: [{
+   211	                  field: fieldConfig.field,
+   212	                  message: `Maximum size is ${fieldConfig.maxSize}, got ${formatSize(file.size)}`
+   213	                }]
+   214	              }
+   215	            )
+   216	          }
+   217	        }
+   218	
+   219	        // Upload to storage
+   220	        if (!fieldConfig.storage) {
+   221	          throw new Error(`No storage configured for file field '${fieldConfig.field}'`)
+   222	        }
+   223	
+   224	        try {
+   225	          const storedUrl = await fieldConfig.storage.upload(file)
+   226	          fields[fieldConfig.field] = storedUrl
+   227	          log.debug(`Uploaded file for field '${fieldConfig.field}' to: ${storedUrl}`)
+   228	        } catch (error) {
+   229	          // Cleanup if file has cleanup function
+   230	          if (file.cleanup) {
+   231	            try {
+   232	              await file.cleanup()
+   233	            } catch (cleanupError) {
+   234	              log.warn('Failed to cleanup file after upload error:', cleanupError)
+   235	            }
+   236	          }
+   237	
+   238	          throw new RestApiValidationError(
+   239	            `Failed to upload file for field '${fieldConfig.field}': ${error.message}`,
+   240	            {
+   241	              fields: [fieldConfig.field],
+   242	              violations: [{
+   243	                field: fieldConfig.field,
+   244	                message: error.message
+   245	              }]
+   246	            }
+   247	          )
+   248	        }
+   249	      }
+   250	
+   251	      // Replace inputRecord with processed data
+   252	      if (!params.inputRecord) {
+   253	        params.inputRecord = { data: { attributes: {} } }
+   254	      }
+   255	      if (!params.inputRecord.data) {
+   256	        params.inputRecord.data = { attributes: {} }
+   257	      }
+   258	      if (!params.inputRecord.data.attributes) {
+   259	        params.inputRecord.data.attributes = {}
+   260	      }
+   261	
+   262	      // Merge fields into attributes
+   263	      Object.assign(params.inputRecord.data.attributes, fields)
+   264	
+   265	      // Cleanup any remaining temp files
+   266	      for (const file of Object.values(files)) {
+   267	        if (file.cleanup) {
+   268	          try {
+   269	            await file.cleanup()
+   270	          } catch (error) {
+   271	            log.warn('Failed to cleanup temp file:', error)
+   272	          }
+   273	        }
+   274	      }
+   275	    }
+   276	
+   277	    /**
+   278	     * Hook into REST API methods to process files
+   279	     */
+   280	    addHook('beforeProcessing', 'processFiles', {}, async ({ context }) => {
+   281	      const method = context.method
+   282	      const scopeName = context.scopeName
+   283	      const params = context.params
+   284	
+   285	      // Only process for mutation methods
+   286	      if (!['post', 'put', 'patch'].includes(method)) {
+   287	        return
+   288	      }
+   289	
+   290	      // Process files if this scope has file fields
+   291	      await processFiles(scopeName, params, context)
+   292	    })
+   293	
+   294	    log.info('File handling plugin initialized successfully')
+   295	  }
+   296	}
+   297	
+   298	/**
+   299	 * Parse size string to bytes
+   300	 * @param {string} size - Size string like '10mb', '1.5GB'
+   301	 * @returns {number} Size in bytes
+   302	 */
+   303	function parseSize (size) {
+   304	  const units = {
+   305	    b: 1,
+   306	    kb: 1024,
+   307	    mb: 1024 * 1024,
+   308	    gb: 1024 * 1024 * 1024
+   309	  }
+   310	
+   311	  const match = size.toLowerCase().match(/^(\d+(?:\.\d+)?)\s*([a-z]+)$/)
+   312	  if (!match) {
+   313	    throw new Error(`Invalid size format: ${size}`)
+   314	  }
+   315	
+   316	  const [, num, unit] = match
+   317	  const multiplier = units[unit]
+   318	
+   319	  if (!multiplier) {
+   320	    throw new Error(`Unknown size unit: ${unit}`)
+   321	  }
+   322	
+   323	  return parseFloat(num) * multiplier
+   324	}
+   325	
+   326	/**
+   327	 * Format bytes to human readable size
+   328	 * @param {number} bytes - Size in bytes
+   329	 * @returns {string} Human readable size
+   330	 */
+   331	function formatSize (bytes) {
+   332	  const units = ['B', 'KB', 'MB', 'GB']
+   333	  let size = bytes
+   334	  let unitIndex = 0
+   335	
+   336	  while (size >= 1024 && unitIndex < units.length - 1) {
+   337	    size /= 1024
+   338	    unitIndex++
+   339	  }
+   340	
+   341	  return `${size.toFixed(1)}${units[unitIndex]}`
+   342	}

package/audit/evidence/code/critical-pass1/json-rest-api__plugins__core__lib__dbTablesOperations.js.txt

@@ -0,0 +1,304 @@
+     1	/**
+     2	 * @file Creates Knex table definitions from json-rest-schema definitions
+     3	 */
+     4	
+     5	/**
+     6	 * Maps json-rest-schema types to Knex column types
+     7	 * @param {object} table - The Knex table builder instance
+     8	 * @param {string} columnName - The name of the column
+     9	 * @param {object} definition - The schema definition for the field
+    10	 * @returns {object} The Knex column builder instance
+    11	 */
+    12	function mapTypeToKnex (table, columnName, definition) {
+    13	  const { type, precision, scale, maxLength, unsigned } = definition
+    14	
+    15	  switch (type) {
+    16	    case 'string':
+    17	      return maxLength ? table.string(columnName, maxLength) : table.string(columnName)
+    18	
+    19	    case 'number':
+    20	      if (precision !== undefined && scale !== undefined) {
+    21	        return table.decimal(columnName, precision, scale)
+    22	      }
+    23	      return table.float(columnName)
+    24	
+    25	    case 'id':
+    26	      const col = table.integer(columnName)
+    27	      return unsigned !== false ? col.unsigned() : col
+    28	
+    29	    case 'boolean':
+    30	      return table.boolean(columnName)
+    31	
+    32	    case 'date':
+    33	      return table.date(columnName)
+    34	
+    35	    case 'dateTime':
+    36	      return table.datetime(columnName)
+    37	
+    38	    case 'time':
+    39	      return table.time(columnName)
+    40	
+    41	    case 'timestamp':
+    42	      return table.integer(columnName)
+    43	
+    44	    case 'array':
+    45	    case 'object':
+    46	    case 'serialize':
+    47	      return table.json(columnName)
+    48	
+    49	    case 'blob':
+    50	    case 'file':
+    51	      return table.binary(columnName)
+    52	
+    53	    case 'none':
+    54	    default:
+    55	      return table.string(columnName)
+    56	  }
+    57	}
+    58	
+    59	/**
+    60	 * Applies schema constraints to a Knex column
+    61	 * @param {object} column - The Knex column builder instance
+    62	 * @param {object} definition - The schema definition for the field
+    63	 */
+    64	function applyConstraints (column, definition) {
+    65	  // Nullability
+    66	  if (definition.nullable === true) {
+    67	    column.nullable()
+    68	  } else if (definition.required === true || definition.nullable === false) {
+    69	    column.notNullable()
+    70	  }
+    71	
+    72	  // Default value
+    73	  if (definition.defaultTo !== undefined) {
+    74	    column.defaultTo(definition.defaultTo)
+    75	  }
+    76	
+    77	  // Database-specific constraints
+    78	  if (definition.unique === true) {
+    79	    column.unique()
+    80	  }
+    81	
+    82	  if (definition.primary === true) {
+    83	    column.primary()
+    84	  }
+    85	
+    86	  if (definition.index === true) {
+    87	    column.index()
+    88	  }
+    89	
+    90	  if (definition.references) {
+    91	    column.references(definition.references.column || 'id')
+    92	      .inTable(definition.references.table)
+    93	
+    94	    if (definition.references.onDelete) {
+    95	      column.onDelete(definition.references.onDelete)
+    96	    }
+    97	
+    98	    if (definition.references.onUpdate) {
+    99	      column.onUpdate(definition.references.onUpdate)
+   100	    }
+   101	  }
+   102	
+   103	  if (definition.comment) {
+   104	    column.comment(definition.comment)
+   105	  }
+   106	}
+   107	
+   108	/**
+   109	 * Creates a Knex table from a json-rest-schema definition
+   110	 * @param {object} knex - The Knex instance
+   111	 * @param {string} tableName - The name of the table to create
+   112	 * @param {object} schema - The json-rest-schema instance
+   113	 * @param {string} [idProperty='id'] - The name of the ID column
+   114	 * @param {object} [options={}] - Additional options
+   115	 * @param {boolean} [options.autoIncrement=true] - Whether to use auto-incrementing IDs
+   116	 * @param {boolean} [options.timestamps=false] - Whether to add created_at/updated_at columns
+   117	 * @returns {Promise} A promise that resolves when the table is created
+   118	 */
+   119	export async function createKnexTable (knex, schemaInfo, tableSchemaInstance, options = {}) {
+   120	  const { autoIncrement = true, timestamps = false } = options
+   121	
+   122	  const tableName = schemaInfo.tableName
+   123	  const idProperty = schemaInfo.idProperty
+   124	  const tableSchemaStructure = tableSchemaInstance.structure
+   125	
+   126	  return knex.schema.createTable(tableName, (table) => {
+   127	    // Check if schema has the idProperty field with primary key
+   128	    const hasIdField = tableSchemaStructure[idProperty] && tableSchemaStructure[idProperty].primary === true
+   129	
+   130	    // Add auto-incrementing ID if no primary key is defined and autoIncrement is true
+   131	    if (!hasIdField && autoIncrement) {
+   132	      table.increments(idProperty).primary()
+   133	    }
+   134	
+   135	    // Process each field in the schema
+   136	    for (const [fieldName, definition] of Object.entries(tableSchemaStructure)) {
+   137	      // Skip if this is the ID field and we already handled it
+   138	      if (fieldName === idProperty && !hasIdField && autoIncrement) {
+   139	        continue
+   140	      }
+   141	
+   142	      // Create the column with the appropriate type
+   143	      const column = mapTypeToKnex(table, fieldName, definition)
+   144	
+   145	      // Apply constraints
+   146	      applyConstraints(column, definition)
+   147	    }
+   148	
+   149	    // Add timestamps if requested
+   150	    if (timestamps) {
+   151	      table.timestamps(true, true)
+   152	    }
+   153	  })
+   154	}
+   155	
+   156	export async function addKnexFields (knex, tableName, schema) {
+   157	  return knex.schema.alterTable(tableName, (table) => {
+   158	    for (const [fieldName, definition] of Object.entries(schema.structure)) {
+   159	      const column = mapTypeToKnex(table, fieldName, definition)
+   160	      applyConstraints(column, definition)
+   161	    }
+   162	  })
+   163	}
+   164	
+   165	// Helper function to alter multiple fields in an existing table
+   166	export async function alterKnexFields (knex, tableName, fields, options = {}) {
+   167	  return knex.schema.alterTable(tableName, (table) => {
+   168	    for (const [fieldName, definition] of Object.entries(fields)) {
+   169	      // Create the column with alter flag
+   170	      const column = mapTypeToKnex(table, fieldName, definition)
+   171	
+   172	      // Mark this as an alteration
+   173	      column.alter()
+   174	
+   175	      // Apply constraints (these will be reapplied with the alter)
+   176	      applyConstraints(column, definition)
+   177	    }
+   178	  })
+   179	}
+   180	
+   181	/**
+   182	 * Generates a Knex migration string from a json-rest-schema definition
+   183	 * @param {string} tableName - The name of the table
+   184	 * @param {object} schema - The json-rest-schema instance
+   185	 * @param {object} [options={}] - Additional options
+   186	 * @returns {string} The migration code as a string
+   187	 */
+   188	export function generateKnexMigration (tableName, schema, options = {}) {
+   189	  const { autoIncrement = true, timestamps = false } = options
+   190	
+   191	  let migration = `exports.up = function(knex) {
+   192	  return knex.schema.createTable('${tableName}', (table) => {\n`
+   193	
+   194	  // Check if schema has an 'id' field with primary key
+   195	  const hasIdField = schema.structure.id && schema.structure.id.primary === true
+   196	
+   197	  // Add auto-incrementing ID if needed
+   198	  if (!hasIdField && autoIncrement) {
+   199	    migration += '    table.increments(\'id\').primary();\n'
+   200	  }
+   201	
+   202	  // Process each field
+   203	  for (const [fieldName, definition] of Object.entries(schema.structure)) {
+   204	    if (fieldName === 'id' && !hasIdField && autoIncrement) {
+   205	      continue
+   206	    }
+   207	
+   208	    let line = '    '
+   209	
+   210	    // Map type
+   211	    switch (definition.type) {
+   212	      case 'string':
+   213	        line += definition.maxLength
+   214	          ? `table.string('${fieldName}', ${definition.maxLength})`
+   215	          : `table.string('${fieldName}')`
+   216	        break
+   217	      case 'number':
+   218	        if (definition.precision !== undefined && definition.scale !== undefined) {
+   219	          line += `table.decimal('${fieldName}', ${definition.precision}, ${definition.scale})`
+   220	        } else {
+   221	          line += `table.float('${fieldName}')`
+   222	        }
+   223	        break
+   224	      case 'id':
+   225	        line += `table.integer('${fieldName}')`
+   226	        if (definition.unsigned !== false) line += '.unsigned()'
+   227	        break
+   228	      case 'boolean':
+   229	        line += `table.boolean('${fieldName}')`
+   230	        break
+   231	      case 'date':
+   232	        line += `table.date('${fieldName}')`
+   233	        break
+   234	      case 'dateTime':
+   235	        line += `table.datetime('${fieldName}')`
+   236	        break
+   237	      case 'time':
+   238	        line += `table.time('${fieldName}')`
+   239	        break
+   240	      case 'timestamp':
+   241	        line += `table.integer('${fieldName}')`
+   242	        break
+   243	      case 'array':
+   244	      case 'object':
+   245	      case 'serialize':
+   246	        line += `table.json('${fieldName}')`
+   247	        break
+   248	      case 'blob':
+   249	      case 'file':
+   250	        line += `table.binary('${fieldName}')`
+   251	        break
+   252	      default:
+   253	        line += `table.string('${fieldName}')`
+   254	    }
+   255	
+   256	    // Add constraints
+   257	    if (definition.nullable === true) {
+   258	      line += '.nullable()'
+   259	    } else if (definition.required === true || definition.nullable === false) {
+   260	      line += '.notNullable()'
+   261	    }
+   262	
+   263	    if (definition.defaultTo !== undefined) {
+   264	      const defaultValue = typeof definition.defaultTo === 'string'
+   265	        ? `'${definition.defaultTo}'`
+   266	        : definition.defaultTo
+   267	      line += `.defaultTo(${defaultValue})`
+   268	    }
+   269	
+   270	    if (definition.unique === true) line += '.unique()'
+   271	    if (definition.primary === true) line += '.primary()'
+   272	    if (definition.index === true) line += '.index()'
+   273	
+   274	    if (definition.references) {
+   275	      const refCol = definition.references.column || 'id'
+   276	      line += `.references('${refCol}').inTable('${definition.references.table}')`
+   277	      if (definition.references.onDelete) {
+   278	        line += `.onDelete('${definition.references.onDelete}')`
+   279	      }
+   280	      if (definition.references.onUpdate) {
+   281	        line += `.onUpdate('${definition.references.onUpdate}')`
+   282	      }
+   283	    }
+   284	
+   285	    if (definition.comment) {
+   286	      line += `.comment('${definition.comment}')`
+   287	    }
+   288	
+   289	    migration += line + ';\n'
+   290	  }
+   291	
+   292	  if (timestamps) {
+   293	    migration += '    table.timestamps(true, true);\n'
+   294	  }
+   295	
+   296	  migration += `  });
+   297	};
+   298	
+   299	exports.down = function(knex) {
+   300	  return knex.schema.dropTable('${tableName}');
+   301	};`
+   302	
+   303	  return migration
+   304	}