s3db.js 13.4.0 → 13.6.0

package/src/plugins/shared/response-formatter.js

@@ -0,0 +1,264 @@
+/**
+ * Response Formatter - Standard JSON API responses
+ *
+ * Provides consistent response formatting across all API endpoints
+ */
+
+/**
+ * Format successful response
+ * @param {Object} data - Response data
+ * @param {Object} options - Response options
+ * @param {number} options.status - HTTP status code (default: 200)
+ * @param {Object} options.meta - Additional metadata
+ * @returns {Object} Formatted response
+ */
+export function success(data, options = {}) {
+  const { status = 200, meta = {} } = options;
+
+  return {
+    success: true,
+    data,
+    meta: {
+      timestamp: new Date().toISOString(),
+      ...meta
+    },
+    _status: status
+  };
+}
+
+/**
+ * Format error response
+ * @param {string|Error} error - Error message or Error object
+ * @param {Object} options - Error options
+ * @param {number} options.status - HTTP status code (default: 500)
+ * @param {string} options.code - Error code
+ * @param {Object} options.details - Additional error details
+ * @returns {Object} Formatted error response
+ */
+export function error(error, options = {}) {
+  const { status = 500, code = 'INTERNAL_ERROR', details = {} } = options;
+
+  const errorMessage = error instanceof Error ? error.message : error;
+  const errorStack = error instanceof Error && process.env.NODE_ENV !== 'production'
+    ? error.stack
+    : undefined;
+
+  return {
+    success: false,
+    error: {
+      message: errorMessage,
+      code,
+      details,
+      stack: errorStack
+    },
+    meta: {
+      timestamp: new Date().toISOString()
+    },
+    _status: status
+  };
+}
+
+/**
+ * Format list response with pagination
+ * @param {Array} items - List items
+ * @param {Object} pagination - Pagination info
+ * @param {number} pagination.total - Total count
+ * @param {number} pagination.page - Current page
+ * @param {number} pagination.pageSize - Items per page
+ * @param {number} pagination.pageCount - Total pages
+ * @returns {Object} Formatted list response
+ */
+export function list(items, pagination = {}) {
+  const { total, page, pageSize, pageCount } = pagination;
+
+  return {
+    success: true,
+    data: items,
+    pagination: {
+      total: total || items.length,
+      page: page || 1,
+      pageSize: pageSize || items.length,
+      pageCount: pageCount || 1
+    },
+    meta: {
+      timestamp: new Date().toISOString()
+    },
+    _status: 200
+  };
+}
+
+/**
+ * Format created response
+ * @param {Object} data - Created resource data
+ * @param {string} location - Resource location URL
+ * @returns {Object} Formatted created response
+ */
+export function created(data, location) {
+  return {
+    success: true,
+    data,
+    meta: {
+      timestamp: new Date().toISOString(),
+      location
+    },
+    _status: 201
+  };
+}
+
+/**
+ * Format no content response
+ * @returns {Object} Formatted no content response
+ */
+export function noContent() {
+  return {
+    success: true,
+    data: null,
+    meta: {
+      timestamp: new Date().toISOString()
+    },
+    _status: 204
+  };
+}
+
+/**
+ * Format validation error response
+ * @param {Array} errors - Validation errors
+ * @returns {Object} Formatted validation error response
+ */
+export function validationError(errors) {
+  return error('Validation failed', {
+    status: 400,
+    code: 'VALIDATION_ERROR',
+    details: { errors }
+  });
+}
+
+/**
+ * Format not found response
+ * @param {string} resource - Resource name
+ * @param {string} id - Resource ID
+ * @returns {Object} Formatted not found response
+ */
+export function notFound(resource, id) {
+  return error(`${resource} with id '${id}' not found`, {
+    status: 404,
+    code: 'NOT_FOUND',
+    details: { resource, id }
+  });
+}
+
+/**
+ * Format unauthorized response
+ * @param {string} message - Unauthorized message
+ * @returns {Object} Formatted unauthorized response
+ */
+export function unauthorized(message = 'Unauthorized') {
+  return error(message, {
+    status: 401,
+    code: 'UNAUTHORIZED'
+  });
+}
+
+/**
+ * Format forbidden response
+ * @param {string} message - Forbidden message
+ * @returns {Object} Formatted forbidden response
+ */
+export function forbidden(message = 'Forbidden') {
+  return error(message, {
+    status: 403,
+    code: 'FORBIDDEN'
+  });
+}
+
+/**
+ * Format rate limit exceeded response
+ * @param {number} retryAfter - Retry after seconds
+ * @returns {Object} Formatted rate limit response
+ */
+export function rateLimitExceeded(retryAfter) {
+  return error('Rate limit exceeded', {
+    status: 429,
+    code: 'RATE_LIMIT_EXCEEDED',
+    details: { retryAfter }
+  });
+}
+
+/**
+ * Format payload too large response
+ * @param {number} size - Received payload size in bytes
+ * @param {number} limit - Maximum allowed size in bytes
+ * @returns {Object} Formatted payload too large response
+ */
+export function payloadTooLarge(size, limit) {
+  return error('Request payload too large', {
+    status: 413,
+    code: 'PAYLOAD_TOO_LARGE',
+    details: {
+      receivedSize: size,
+      maxSize: limit,
+      receivedMB: (size / 1024 / 1024).toFixed(2),
+      maxMB: (limit / 1024 / 1024).toFixed(2)
+    }
+  });
+}
+
+/**
+ * Create custom formatters with override support
+ *
+ * Allows customization of response formats while maintaining fallbacks.
+ * Useful for adapting to existing API contracts or organizational standards.
+ *
+ * @param {Object} customFormatters - Custom formatter functions
+ * @param {Function} customFormatters.success - Custom success formatter
+ * @param {Function} customFormatters.error - Custom error formatter
+ * @param {Function} customFormatters.list - Custom list formatter
+ * @param {Function} customFormatters.created - Custom created formatter
+ * @returns {Object} Formatters object with custom overrides
+ *
+ * @example
+ * const formatters = createCustomFormatters({
+ *   success: (data, meta) => ({ ok: true, result: data, ...meta }),
+ *   error: (err, status) => ({ ok: false, message: err.message, code: status })
+ * });
+ *
+ * // Use in API routes:
+ * return c.json(formatters.success(user));
+ */
+export function createCustomFormatters(customFormatters = {}) {
+  // Default formatters
+  const defaults = {
+    success: (data, meta = {}) => success(data, { meta }),
+    error: (err, status, code) => error(err, { status, code }),
+    list: (items, pagination) => list(items, pagination),
+    created: (data, location) => created(data, location),
+    noContent: () => noContent(),
+    validationError: (errors) => validationError(errors),
+    notFound: (resource, id) => notFound(resource, id),
+    unauthorized: (message) => unauthorized(message),
+    forbidden: (message) => forbidden(message),
+    rateLimitExceeded: (retryAfter) => rateLimitExceeded(retryAfter),
+    payloadTooLarge: (size, limit) => payloadTooLarge(size, limit)
+  };
+
+  // Merge custom formatters with defaults
+  return {
+    ...defaults,
+    ...customFormatters
+  };
+}
+
+export default {
+  success,
+  error,
+  list,
+  created,
+  noContent,
+  validationError,
+  notFound,
+  unauthorized,
+  forbidden,
+  rateLimitExceeded,
+  payloadTooLarge,
+  createCustomFormatters
+};

package/src/plugins/state-machine.plugin.js

@@ -133,10 +133,46 @@ export class StateMachinePlugin extends Plugin {
     this.machines = new Map();
     this.triggerIntervals = [];
     this.schedulerPlugin = null;
+    this._pendingEventHandlers = new Set();
 
     this._validateConfiguration();
   }
 
+  /**
+   * Wait for all pending event handlers to complete
+   * Useful when working with async events (asyncEvents: true)
+   * @param {number} timeout - Maximum time to wait in milliseconds (default: 5000)
+   * @returns {Promise<void>}
+   */
+  async waitForPendingEvents(timeout = 5000) {
+    if (this._pendingEventHandlers.size === 0) {
+      return; // No pending events
+    }
+
+    const startTime = Date.now();
+
+    while (this._pendingEventHandlers.size > 0) {
+      if (Date.now() - startTime > timeout) {
+        throw new StateMachineError(
+          `Timeout waiting for ${this._pendingEventHandlers.size} pending event handlers`,
+          {
+            operation: 'waitForPendingEvents',
+            pendingCount: this._pendingEventHandlers.size,
+            timeout
+          }
+        );
+      }
+
+      // Wait for at least one handler to complete
+      if (this._pendingEventHandlers.size > 0) {
+        await Promise.race(Array.from(this._pendingEventHandlers));
+      }
+
+      // Small delay before checking again
+      await new Promise(resolve => setImmediate(resolve));
+    }
+  }
+
   _validateConfiguration() {
     if (!this.config.stateMachines || Object.keys(this.config.stateMachines).length === 0) {
       throw new StateMachineError('At least one state machine must be defined', {
@@ -1331,10 +1367,29 @@ export class StateMachinePlugin extends Plugin {
       // Resource events are typically: inserted, updated, deleted
       const baseEvent = typeof baseEventName === 'function' ? 'updated' : baseEventName;
 
-      eventSource.on(baseEvent, eventHandler);
+      // IMPORTANT: For resources with async events, we need to ensure the event handler
+      // completes before returning control. We wrap the handler to track pending operations.
+      const wrappedHandler = async (...args) => {
+        // Track this as a pending operation
+        const handlerPromise = eventHandler(...args);
+
+        // Store promise if state machine has event tracking
+        if (!this._pendingEventHandlers) {
+          this._pendingEventHandlers = new Set();
+        }
+        this._pendingEventHandlers.add(handlerPromise);
+
+        try {
+          await handlerPromise;
+        } finally {
+          this._pendingEventHandlers.delete(handlerPromise);
+        }
+      };
+
+      eventSource.on(baseEvent, wrappedHandler);
 
       if (this.config.verbose) {
-        console.log(`[StateMachinePlugin] Listening to resource event '${baseEvent}' from '${eventSource.name}' for trigger '${triggerName}'`);
+        console.log(`[StateMachinePlugin] Listening to resource event '${baseEvent}' from '${eventSource.name}' for trigger '${triggerName}' (async-safe)`);
       }
     } else {
       // Original behavior: listen to database or plugin events

package/src/resource.class.js

@@ -1,7 +1,6 @@
 import { join } from "path";
 import { createHash } from "crypto";
 import AsyncEventEmitter from "./concerns/async-event-emitter.js";
-import { customAlphabet, urlAlphabet } from 'nanoid';
 import jsonStableStringify from "json-stable-stringify";
 import { PromisePool } from "@supercharge/promise-pool";
 import { chunk, cloneDeep, merge, isEmpty, isObject } from "lodash-es";
@@ -12,7 +11,7 @@ import { streamToString } from "./stream/index.js";
 import tryFn, { tryFnSync } from "./concerns/try-fn.js";
 import { ResourceReader, ResourceWriter } from "./stream/index.js"
 import { getBehavior, DEFAULT_BEHAVIOR } from "./behaviors/index.js";
-import { idGenerator as defaultIdGenerator } from "./concerns/id.js";
+import { idGenerator as defaultIdGenerator, createCustomGenerator, getUrlAlphabet } from "./concerns/id.js";
 import { calculateTotalSize, calculateEffectiveLimit } from "./concerns/calculator.js";
 import { mapAwsError, InvalidResourceItem, ResourceError, PartitionError, ValidationError } from "./errors.js";
 
@@ -26,7 +25,8 @@ export class Resource extends AsyncEventEmitter {
    * @param {string} [config.version='v1'] - Resource version
    * @param {Object} [config.attributes={}] - Resource attributes schema
    * @param {string} [config.behavior='user-managed'] - Resource behavior strategy
-   * @param {string} [config.passphrase='secret'] - Encryption passphrase
+   * @param {string} [config.passphrase='secret'] - Encryption passphrase (for 'secret' type)
+   * @param {number} [config.bcryptRounds=10] - Bcrypt rounds (for 'password' type)
    * @param {number} [config.parallelism=10] - Parallelism for bulk operations
    * @param {Array} [config.observers=[]] - Observer instances
    * @param {boolean} [config.cache=false] - Enable caching
@@ -123,6 +123,7 @@ export class Resource extends AsyncEventEmitter {
       attributes = {},
       behavior = DEFAULT_BEHAVIOR,
       passphrase = 'secret',
+      bcryptRounds = 10,
       parallelism = 10,
       observers = [],
       cache = false,
@@ -140,7 +141,8 @@ export class Resource extends AsyncEventEmitter {
       asyncEvents = true,
       asyncPartitions = true,
       strictPartitions = false,
-      createdBy = 'user'
+      createdBy = 'user',
+      guard
     } = config;
 
     // Set instance properties
@@ -151,6 +153,7 @@ export class Resource extends AsyncEventEmitter {
     this.observers = observers;
     this.parallelism = parallelism;
     this.passphrase = passphrase ?? 'secret';
+    this.bcryptRounds = bcryptRounds;
     this.versioningEnabled = versioningEnabled;
     this.strictValidation = strictValidation;
     
@@ -281,6 +284,10 @@ export class Resource extends AsyncEventEmitter {
       }
     }
 
+    // --- GUARDS SYSTEM ---
+    // Normalize and store guards (framework-agnostic authorization)
+    this.guard = this._normalizeGuard(guard);
+
     // --- MIDDLEWARE SYSTEM ---
     this._initMiddleware();
     // Debug: print method names and typeof update at construction
@@ -303,11 +310,11 @@ export class Resource extends AsyncEventEmitter {
     }
     // If customIdGenerator is a number (size), create a generator with that size
     if (typeof customIdGenerator === 'number' && customIdGenerator > 0) {
-      return customAlphabet(urlAlphabet, customIdGenerator);
+      return createCustomGenerator(getUrlAlphabet(), customIdGenerator);
     }
     // If idSize is provided, create a generator with that size
     if (typeof idSize === 'number' && idSize > 0 && idSize !== 22) {
-      return customAlphabet(urlAlphabet, idSize);
+      return createCustomGenerator(getUrlAlphabet(), idSize);
     }
     // Default to the standard idGenerator (22 chars)
     return defaultIdGenerator;
@@ -400,6 +407,7 @@ export class Resource extends AsyncEventEmitter {
       name: this.name,
       attributes: this.attributes,
       passphrase: this.passphrase,
+      bcryptRounds: this.bcryptRounds,
       version: this.version,
       options: {
         autoDecrypt: this.config.autoDecrypt,
@@ -1060,9 +1068,7 @@ export class Resource extends AsyncEventEmitter {
    * });
    */
   async insert({ id, ...attributes }) {
-    const exists = await this.exists(id);
-    if (exists) throw new Error(`Resource with id '${id}' already exists`);
-    const keyDebug = this.getResourceKey(id || '(auto)');
+    const providedId = id !== undefined && id !== null && String(id).trim() !== '';
     if (this.config.timestamps) {
       attributes.createdAt = new Date().toISOString();
       attributes.updatedAt = new Date().toISOString();
@@ -1086,11 +1092,12 @@ export class Resource extends AsyncEventEmitter {
     const extraData = {};
     for (const k of extraProps) extraData[k] = preProcessedData[k];
 
+    const shouldValidateId = preProcessedData.id !== undefined && preProcessedData.id !== null;
     const {
       errors,
       isValid,
       data: validated,
-    } = await this.validate(preProcessedData, { includeId: true });
+    } = await this.validate(preProcessedData, { includeId: shouldValidateId });
 
     if (!isValid) {
       const errorMsg = (errors && errors.length && errors[0].message) ? errors[0].message : 'Insert failed';
@@ -1109,7 +1116,7 @@ export class Resource extends AsyncEventEmitter {
     Object.assign(validatedAttributes, extraData);
     
     // Generate ID with fallback for empty generators
-    let finalId = validatedId || id;
+    let finalId = validatedId || preProcessedData.id || id;
     if (!finalId) {
       finalId = this.idGenerator();
       // Fallback to default generator if custom generator returns empty
@@ -1133,6 +1140,31 @@ export class Resource extends AsyncEventEmitter {
 
     // Add version metadata (required for all objects)
     const finalMetadata = processedMetadata;
+
+    if (!finalId || String(finalId).trim() === '') {
+      throw new InvalidResourceItem({
+        bucket: this.client.config.bucket,
+        resourceName: this.name,
+        attributes: preProcessedData,
+        validation: [{ message: 'Generated ID is invalid', field: 'id' }],
+        message: 'Generated ID is invalid'
+      });
+    }
+
+    const shouldCheckExists = providedId || shouldValidateId || validatedId !== undefined;
+    if (shouldCheckExists) {
+      const alreadyExists = await this.exists(finalId);
+      if (alreadyExists) {
+        throw new InvalidResourceItem({
+          bucket: this.client.config.bucket,
+          resourceName: this.name,
+          attributes: preProcessedData,
+          validation: [{ message: `Resource with id '${finalId}' already exists`, field: 'id' }],
+          message: `Resource with id '${finalId}' already exists`
+        });
+      }
+    }
+
     const key = this.getResourceKey(finalId);
     // Determine content type based on body content
     let contentType = undefined;
@@ -3653,6 +3685,102 @@ export class Resource extends AsyncEventEmitter {
     return filtered;
   }
 
+  // --- GUARDS SYSTEM ---
+  /**
+   * Normalize guard configuration
+   * @param {Object|Array|undefined} guard - Guard configuration
+   * @returns {Object|null} Normalized guard config
+   * @private
+   */
+  _normalizeGuard(guard) {
+    if (!guard) return null;
+
+    // String array simples → aplica para todas as operações
+    if (Array.isArray(guard)) {
+      return { '*': guard };
+    }
+
+    return guard;
+  }
+
+  /**
+   * Execute guard for operation
+   * @param {string} operation - Operation name (list, get, insert, update, etc)
+   * @param {Object} context - Framework-agnostic context
+   * @param {Object} context.user - Decoded JWT token
+   * @param {Object} context.params - Route params
+   * @param {Object} context.body - Request body
+   * @param {Object} context.query - Query string
+   * @param {Object} context.headers - Request headers
+   * @param {Function} context.setPartition - Helper to set partition
+   * @param {Object} [resource] - Resource record (for get/update/delete)
+   * @returns {Promise<boolean>} True if allowed, false if denied
+   */
+  async executeGuard(operation, context, resource = null) {
+    if (!this.guard) return true;  // No guard = allow
+
+    // 1. Try operation-specific guard
+    let guardFn = this.guard[operation];
+
+    // 2. Fallback to wildcard
+    if (!guardFn) {
+      guardFn = this.guard['*'];
+    }
+
+    // 3. No guard = allow
+    if (!guardFn) return true;
+
+    // 4. Boolean simple
+    if (typeof guardFn === 'boolean') {
+      return guardFn;
+    }
+
+    // 5. Array of roles/scopes
+    if (Array.isArray(guardFn)) {
+      return this._checkRolesScopes(guardFn, context.user);
+    }
+
+    // 6. Custom function
+    if (typeof guardFn === 'function') {
+      try {
+        const result = await guardFn(context, resource);
+        return result === true;  // Force boolean
+      } catch (err) {
+        // Guard error = deny access
+        console.error(`Guard error for ${operation}:`, err);
+        return false;
+      }
+    }
+
+    return false;  // Default: deny
+  }
+
+  /**
+   * Check if user has required roles or scopes
+   * @param {Array<string>} requiredRolesScopes - Required roles/scopes
+   * @param {Object} user - User from JWT token
+   * @returns {boolean} True if user has any of required roles/scopes
+   * @private
+   */
+  _checkRolesScopes(requiredRolesScopes, user) {
+    if (!user) return false;
+
+    // User scopes (OpenID scope claim)
+    const userScopes = user.scope?.split(' ') || [];
+
+    // User roles - support multiple formats (Keycloak, Azure AD)
+    const clientId = user.azp || process.env.CLIENT_ID || 'default';
+    const clientRoles = user.resource_access?.[clientId]?.roles || [];
+    const realmRoles = user.realm_access?.roles || [];
+    const azureRoles = user.roles || [];
+    const userRoles = [...clientRoles, ...realmRoles, ...azureRoles];
+
+    // Check if user has any of required
+    return requiredRolesScopes.some(required => {
+      return userScopes.includes(required) || userRoles.includes(required);
+    });
+  }
+
   // --- MIDDLEWARE SYSTEM ---
   _initMiddleware() {
     // Map of methodName -> array of middleware functions
@@ -4012,4 +4140,4 @@ function validateResourceConfig(config) {
   };
 }
 
-export default Resource;
+export default Resource;

package/src/schema.class.js

@@ -13,6 +13,7 @@ import {
 } from "lodash-es";
 
 import { encrypt, decrypt } from "./concerns/crypto.js";
+import { hashPassword, compactHash } from "./concerns/password-hashing.js";
 import { ValidatorManager } from "./validator.class.js";
 import { tryFn, tryFnSync } from "./concerns/try-fn.js";
 import { SchemaError } from "./errors.js";
@@ -121,6 +122,16 @@ export const SchemaActions = {
     return raw;
   },
 
+  hashPassword: async (value, { bcryptRounds = 10 }) => {
+    if (value === null || value === undefined) return value;
+    // Hash with bcrypt
+    const [okHash, errHash, hash] = await tryFn(() => hashPassword(String(value), bcryptRounds));
+    if (!okHash) return value; // Return original on error
+    // Compact hash to save space (60 → 53 bytes)
+    const [okCompact, errCompact, compacted] = tryFnSync(() => compactHash(hash));
+    return okCompact ? compacted : hash; // Return compacted or fallback to full hash
+  },
+
   toString: (value) => value == null ? value : String(value),
 
   fromArray: (value, { separator }) => {
@@ -535,6 +546,7 @@ export class Schema {
       name,
       attributes,
       passphrase,
+      bcryptRounds,
       version = 1,
       options = {},
       _pluginAttributeMetadata,
@@ -545,6 +557,7 @@ export class Schema {
     this.version = version;
     this.attributes = attributes || {};
     this.passphrase = passphrase ?? "secret";
+    this.bcryptRounds = bcryptRounds ?? 10;
     this.options = merge({}, this.defaultOptions(), options);
     this.allNestedObjectsOptional = this.options.allNestedObjectsOptional ?? false;
 
@@ -555,7 +568,11 @@ export class Schema {
     // Preprocess attributes to handle nested objects for validator compilation
     const processedAttributes = this.preprocessAttributesForValidation(this.attributes);
 
-    this.validator = new ValidatorManager({ autoEncrypt: false }).compile(merge(
+    this.validator = new ValidatorManager({
+      autoEncrypt: false,
+      passphrase: this.passphrase,
+      bcryptRounds: this.bcryptRounds
+    }).compile(merge(
       { $$async: true, $$strict: false },
       processedAttributes,
     ))
@@ -824,6 +841,16 @@ export class Schema {
         continue;
       }
 
+      // Handle passwords
+      if (defStr.includes("password") || defType === 'password') {
+        if (this.options.autoEncrypt) {
+          this.addHook("beforeMap", name, "hashPassword");
+        }
+        // No afterUnmap hook - passwords are one-way hashed
+        // Skip other processing for passwords
+        continue;
+      }
+
       // Handle ip4 type
       if (defStr.includes("ip4") || defType === 'ip4') {
         this.addHook("beforeMap", name, "encodeIPv4");
@@ -1067,6 +1094,7 @@ export class Schema {
         if (value !== undefined && typeof SchemaActions[actionName] === 'function') {
           set(cloned, attribute, await SchemaActions[actionName](value, {
             passphrase: this.passphrase,
+            bcryptRounds: this.bcryptRounds,
             separator: this.options.arraySeparator,
             ...actionParams  // Merge custom parameters (currency, precision, etc.)
           }))
@@ -1181,6 +1209,7 @@ export class Schema {
           if (typeof SchemaActions[actionName] === 'function') {
             parsedValue = await SchemaActions[actionName](parsedValue, {
               passphrase: this.passphrase,
+              bcryptRounds: this.bcryptRounds,
               separator: this.options.arraySeparator,
               ...actionParams  // Merge custom parameters (currency, precision, etc.)
             });