s3db.js 13.6.0 → 14.0.2

package/src/plugins/geo.plugin.js

@@ -1,5 +1,6 @@
 import { Plugin } from "./plugin.class.js";
 import tryFn from "../concerns/try-fn.js";
+import { PluginError } from "../errors.js";
 
 /**
  * GeoPlugin - Geospatial Queries and Location-Based Features
@@ -137,9 +138,14 @@ export class GeoPlugin extends Plugin {
 
     // Validate configuration
     if (!config.latField || !config.lonField) {
-      throw new Error(
-        `[GeoPlugin] Resource "${resourceName}" must have "latField" and "lonField" configured`
-      );
+      throw new PluginError(`[GeoPlugin] Resource "${resourceName}" must have "latField" and "lonField" configured`, {
+        pluginName: 'GeoPlugin',
+        operation: 'setupResource',
+        resourceName,
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Update GeoPlugin configuration with { latField: "...", lonField: "..." } for the resource.'
+      });
     }
 
     if (!config.precision || config.precision < 1 || config.precision > 12) {
@@ -327,7 +333,14 @@ export class GeoPlugin extends Plugin {
      */
     resource.findNearby = async function({ lat, lon, radius = 10, limit = 100 }) {
       if (lat === undefined || lon === undefined) {
-        throw new Error('lat and lon are required for findNearby');
+        throw new PluginError('Latitude and longitude are required for findNearby()', {
+          pluginName: 'GeoPlugin',
+          operation: 'findNearby',
+          resourceName: resource.name,
+          statusCode: 400,
+          retriable: false,
+          suggestion: 'Call findNearby({ lat, lon, radius }) with both coordinates.'
+        });
       }
 
       const longitude = lon; // Alias for internal use
@@ -430,7 +443,14 @@ export class GeoPlugin extends Plugin {
      */
     resource.findInBounds = async function({ north, south, east, west, limit = 100 }) {
       if (north === undefined || south === undefined || east === undefined || west === undefined) {
-        throw new Error('north, south, east, west are required for findInBounds');
+        throw new PluginError('Bounding box requires north, south, east, west coordinates', {
+          pluginName: 'GeoPlugin',
+          operation: 'findInBounds',
+          resourceName: resource.name,
+          statusCode: 400,
+          retriable: false,
+          suggestion: 'Call findInBounds({ north, south, east, west }) with all four boundaries.'
+        });
       }
 
       let allRecords = [];
@@ -536,13 +556,30 @@ export class GeoPlugin extends Plugin {
         ]);
       } catch (err) {
         if (err.name === 'NoSuchKey' || err.message?.includes('No such key')) {
-          throw new Error('One or both records not found');
+          throw new PluginError('One or both records not found for distance calculation', {
+            pluginName: 'GeoPlugin',
+            operation: 'getDistance',
+            resourceName: resource.name,
+            statusCode: 404,
+            retriable: false,
+            suggestion: 'Ensure both record IDs exist before calling getDistance().',
+            ids: [id1, id2],
+            original: err
+          });
         }
         throw err;
       }
 
       if (!record1 || !record2) {
-        throw new Error('One or both records not found');
+        throw new PluginError('One or both records not found for distance calculation', {
+          pluginName: 'GeoPlugin',
+          operation: 'getDistance',
+          resourceName: resource.name,
+          statusCode: 404,
+          retriable: false,
+          suggestion: 'Ensure both record IDs exist before calling getDistance().',
+          ids: [id1, id2]
+        });
       }
 
       const lat1 = record1[config.latField];
@@ -551,7 +588,15 @@ export class GeoPlugin extends Plugin {
       const lon2 = record2[config.lonField];
 
       if (lat1 === undefined || lon1 === undefined || lat2 === undefined || lon2 === undefined) {
-        throw new Error('One or both records missing coordinates');
+        throw new PluginError('One or both records are missing coordinates', {
+          pluginName: 'GeoPlugin',
+          operation: 'getDistance',
+          resourceName: resource.name,
+          statusCode: 422,
+          retriable: false,
+          suggestion: `Check that both records contain ${config.latField} and ${config.lonField} before using geospatial helpers.`,
+          ids: [id1, id2]
+        });
       }
 
       const distance = plugin.calculateDistance(lat1, lon1, lat2, lon2);
@@ -635,7 +680,14 @@ export class GeoPlugin extends Plugin {
       const idx = this.base32.indexOf(chr);
 
       if (idx === -1) {
-        throw new Error(`Invalid geohash character: ${chr}`);
+        throw new PluginError(`Invalid geohash character: ${chr}`, {
+          pluginName: 'GeoPlugin',
+          operation: 'decodeGeohash',
+          statusCode: 400,
+          retriable: false,
+          suggestion: 'Ensure geohash strings use the base32 alphabet 0123456789bcdefghjkmnpqrstuvwxyz.',
+          geohash
+        });
       }
 
       for (let n = 4; n >= 0; n--) {

package/src/plugins/identity/concerns/config.js

@@ -0,0 +1,61 @@
+import {
+  BASE_USER_ATTRIBUTES,
+  BASE_TENANT_ATTRIBUTES,
+  BASE_CLIENT_ATTRIBUTES,
+  validateResourcesConfig,
+  mergeResourceConfig
+} from './resource-schemas.js';
+import { PluginError } from '../../../errors.js';
+
+/**
+ * Validate and normalize user-provided resource configurations.
+ *
+ * @param {Object} resourcesOptions
+ * @returns {{users: Object, tenants: Object, clients: Object}}
+ */
+export function prepareResourceConfigs(resourcesOptions = {}) {
+  const resourcesValidation = validateResourcesConfig(resourcesOptions);
+  if (!resourcesValidation.valid) {
+    throw new PluginError('IdentityPlugin configuration error', {
+      pluginName: 'IdentityPlugin',
+      operation: 'prepareResourceConfigs',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Review the resources configuration and fix the validation errors listed in the metadata.',
+      metadata: { validationErrors: resourcesValidation.errors }
+    });
+  }
+
+  mergeResourceConfig(
+    { attributes: BASE_USER_ATTRIBUTES },
+    resourcesOptions.users,
+    'users'
+  );
+
+  mergeResourceConfig(
+    { attributes: BASE_TENANT_ATTRIBUTES },
+    resourcesOptions.tenants,
+    'tenants'
+  );
+
+  mergeResourceConfig(
+    { attributes: BASE_CLIENT_ATTRIBUTES },
+    resourcesOptions.clients,
+    'clients'
+  );
+
+  return {
+    users: {
+      userConfig: resourcesOptions.users,
+      mergedConfig: null
+    },
+    tenants: {
+      userConfig: resourcesOptions.tenants,
+      mergedConfig: null
+    },
+    clients: {
+      userConfig: resourcesOptions.clients,
+      mergedConfig: null
+    }
+  };
+}

package/src/plugins/identity/concerns/mfa-manager.js

@@ -30,6 +30,7 @@
 
 import { requirePluginDependency } from '../../concerns/plugin-dependencies.js';
 import { idGenerator } from '../../../concerns/id.js';
+import { PluginError } from '../../../errors.js';
 
 export class MFAManager {
   constructor(options = {}) {
@@ -64,7 +65,13 @@ export class MFAManager {
    */
   generateEnrollment(accountName) {
     if (!this.OTPAuth) {
-      throw new Error('[MFA] OTPAuth library not initialized');
+      throw new PluginError('[MFA] OTPAuth library not initialized', {
+        pluginName: 'IdentityPlugin',
+        operation: 'mfaGenerateEnrollment',
+        statusCode: 500,
+        retriable: true,
+        suggestion: 'Call MFAManager.initialize() before generating enrollments or ensure otpauth dependency installs successfully.'
+      });
     }
 
     // Generate TOTP secret
@@ -103,7 +110,13 @@ export class MFAManager {
    */
   verifyTOTP(secret, token) {
     if (!this.OTPAuth) {
-      throw new Error('[MFA] OTPAuth library not initialized');
+      throw new PluginError('[MFA] OTPAuth library not initialized', {
+        pluginName: 'IdentityPlugin',
+        operation: 'mfaVerify',
+        statusCode: 500,
+        retriable: true,
+        suggestion: 'Initialize MFAManager before verifying codes and confirm otpauth dependency is available.'
+      });
     }
 
     try {

package/src/plugins/identity/concerns/rate-limit.js

@@ -0,0 +1,124 @@
+/**
+ * Sliding window rate limiter for IP-based throttling
+ */
+
+export class RateLimiter {
+  /**
+   * @param {Object} options
+   * @param {number} options.windowMs - Window size in milliseconds
+   * @param {number} options.max - Maximum number of hits allowed per window
+   */
+  constructor(options = {}) {
+    this.windowMs = options.windowMs ?? 60000;
+    this.max = options.max ?? 10;
+    this.buckets = new Map(); // key -> { count, expiresAt }
+  }
+
+  /**
+   * Consume a token for the given key
+   * @param {string} key - Identifier (usually IP address)
+   * @returns {{allowed: boolean, remaining: number, retryAfter: number}}
+   */
+  consume(key) {
+    if (!this.enabled()) {
+      return { allowed: true, remaining: Infinity, retryAfter: 0 };
+    }
+
+    const now = Date.now();
+    const bucket = this.buckets.get(key);
+
+    if (!bucket || bucket.expiresAt <= now) {
+      const expiresAt = now + this.windowMs;
+      this.buckets.set(key, { count: 1, expiresAt });
+      this._prune(now);
+      return {
+        allowed: true,
+        remaining: Math.max(this.max - 1, 0),
+        retryAfter: 0
+      };
+    }
+
+    if (bucket.count < this.max) {
+      bucket.count += 1;
+      this._prune(now);
+      return {
+        allowed: true,
+        remaining: Math.max(this.max - bucket.count, 0),
+        retryAfter: 0
+      };
+    }
+
+    const retryAfterMs = bucket.expiresAt - now;
+    return {
+      allowed: false,
+      remaining: 0,
+      retryAfter: Math.max(Math.ceil(retryAfterMs / 1000), 1)
+    };
+  }
+
+  /**
+   * Whether the limiter is active
+   * @returns {boolean}
+   */
+  enabled() {
+    return this.max > 0 && this.windowMs > 0;
+  }
+
+  /**
+   * Periodically remove expired buckets
+   * @private
+   */
+  _prune(now) {
+    if (this.buckets.size > 5000) {
+      for (const [key, bucket] of this.buckets.entries()) {
+        if (bucket.expiresAt <= now) {
+          this.buckets.delete(key);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Create Hono middleware for API-style responses
+ * @param {RateLimiter} limiter
+ * @param {(c: import('hono').Context) => string} getKey
+ */
+export function createJsonRateLimitMiddleware(limiter, getKey) {
+  return async (c, next) => {
+    const key = getKey(c);
+    const result = limiter.consume(key);
+
+    if (result.allowed) {
+      return await next();
+    }
+
+    c.header('Retry-After', String(result.retryAfter));
+    return c.json({
+      error: 'too_many_requests',
+      error_description: `Too many requests. Try again in ${result.retryAfter} seconds.`
+    }, 429);
+  };
+}
+
+/**
+ * Create Hono middleware for browser redirect flows (login UI)
+ * @param {RateLimiter} limiter
+ * @param {(c: import('hono').Context) => string} getKey
+ * @param {(retryAfter: number) => string} buildRedirectUrl
+ */
+export function createRedirectRateLimitMiddleware(limiter, getKey, buildRedirectUrl) {
+  return async (c, next) => {
+    const key = getKey(c);
+    const result = limiter.consume(key);
+
+    if (result.allowed) {
+      return await next();
+    }
+
+    const url = buildRedirectUrl(result.retryAfter);
+    return c.redirect(url, 302);
+  };
+}
+
+export default RateLimiter;

package/src/plugins/identity/concerns/resource-schemas.js

@@ -4,6 +4,7 @@
  * These are the REQUIRED attributes that the Identity Plugin needs to function.
  * Users can extend these with custom attributes, but cannot override base fields.
  */
+import { PluginError } from '../../../errors.js';
 
 /**
  * Base attributes for Users resource
@@ -189,7 +190,14 @@ export function mergeResourceConfig(baseConfig, userConfig = {}, resourceType) {
         `Invalid extra attributes for ${resourceType} resource:`,
         ...validation.errors.map(err => `  - ${err}`)
       ].join('\n');
-      throw new Error(errorMsg);
+      throw new PluginError('Invalid extra attributes for identity resource', {
+        pluginName: 'IdentityPlugin',
+        operation: 'mergeResourceConfig',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Update the resource schema to match IdentityPlugin validation requirements.',
+        description: errorMsg
+      });
     }
   }
 

package/src/plugins/identity/concerns/token-generator.js

@@ -10,6 +10,7 @@
 
 import { randomBytes } from 'crypto';
 import { idGenerator } from '../../../concerns/id.js';
+import { PluginError } from '../../../errors.js';
 
 /**
  * Generate a secure random token
@@ -31,7 +32,13 @@ export function generateToken(bytes = 32, encoding = 'hex') {
       return buffer.toString('base64url');
 
     default:
-      throw new Error(`Invalid encoding: ${encoding}. Use 'hex', 'base64', or 'base64url'.`);
+      throw new PluginError(`Invalid encoding: ${encoding}. Use 'hex', 'base64', or 'base64url'.`, {
+        pluginName: 'IdentityPlugin',
+        operation: 'generateToken',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Pass encoding as "hex", "base64", or "base64url" when calling generateToken.'
+      });
   }
 }
 
@@ -122,7 +129,13 @@ export function calculateExpiration(duration) {
     const match = duration.match(/^(\d+)([smhd])$/);
 
     if (!match) {
-      throw new Error(`Invalid duration format: ${duration}. Use '15m', '1h', '7d', etc.`);
+      throw new PluginError(`Invalid duration format: ${duration}. Use '15m', '1h', '7d', etc.`, {
+        pluginName: 'IdentityPlugin',
+        operation: 'calculateExpiration',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Provide durations using number + unit (s, m, h, d), for example "30m" or "1d".'
+      });
     }
 
     const value = parseInt(match[1], 10);
@@ -134,10 +147,22 @@ export function calculateExpiration(duration) {
       case 'h': ms = value * 60 * 60 * 1000; break; // hours
       case 'd': ms = value * 24 * 60 * 60 * 1000; break; // days
       default:
-        throw new Error(`Invalid duration unit: ${unit}`);
+        throw new PluginError(`Invalid duration unit: ${unit}`, {
+          pluginName: 'IdentityPlugin',
+          operation: 'calculateExpiration',
+          statusCode: 400,
+          retriable: false,
+          suggestion: 'Use s, m, h, or d for seconds, minutes, hours, or days respectively.'
+        });
     }
   } else {
-    throw new Error('Duration must be a string or number');
+    throw new PluginError('Duration must be a string or number', {
+      pluginName: 'IdentityPlugin',
+      operation: 'calculateExpiration',
+      statusCode: 400,
+      retriable: false,
+      suggestion: 'Pass durations as milliseconds (number) or a string like "15m".'
+    });
   }
 
   return Date.now() + ms;

package/src/plugins/identity/drivers/auth-driver.interface.js

@@ -0,0 +1,76 @@
+import { PluginError } from '../../../errors.js';
+
+export class AuthDriver {
+  constructor(name, supportedTypes = []) {
+    this.name = name;
+    this.supportedTypes = supportedTypes;
+  }
+
+  /**
+   * Called once during plugin initialization with database/config/resources
+   * @param {Object} context
+   */
+  // eslint-disable-next-line no-unused-vars
+  async initialize(context) {
+    throw new PluginError('AuthDriver.initialize(context) must be implemented by subclasses', {
+      pluginName: 'IdentityPlugin',
+      operation: 'initializeDriver',
+      statusCode: 500,
+      retriable: false,
+      suggestion: `Implement initialize(context) in ${this.constructor.name} or use one of the provided drivers.`
+    });
+  }
+
+  /**
+   * Authenticate a request (password, client credentials, etc)
+   * @param {Object} request
+   */
+  // eslint-disable-next-line no-unused-vars
+  async authenticate(request) {
+    throw new PluginError('AuthDriver.authenticate(request) must be implemented by subclasses', {
+      pluginName: 'IdentityPlugin',
+      operation: 'authenticateDriver',
+      statusCode: 500,
+      retriable: false,
+      suggestion: `Implement authenticate(request) in ${this.constructor.name} to support the configured grant type.`
+    });
+  }
+
+  supportsType(type) {
+    if (!type) return false;
+    return this.supportedTypes.includes(type);
+  }
+
+  /**
+   * Whether the driver supports issuing tokens for the given grant type
+   * @param {string} grantType
+   */
+  // eslint-disable-next-line no-unused-vars
+  supportsGrant(grantType) {
+    return false;
+  }
+
+  /**
+   * Optionally issue tokens (if driver is responsible for it)
+   * @param {Object} payload
+   */
+  // eslint-disable-next-line no-unused-vars
+  async issueTokens(payload) {
+    throw new PluginError(`AuthDriver ${this.name} does not implement issueTokens`, {
+      pluginName: 'IdentityPlugin',
+      operation: 'issueTokens',
+      statusCode: 500,
+      retriable: false,
+      suggestion: 'Provide an issueTokens implementation or delegate token issuance to the OAuth2 server.'
+    });
+  }
+
+  /**
+   * Optionally revoke tokens (if driver manages them)
+   * @param {Object} payload
+   */
+  // eslint-disable-next-line no-unused-vars
+  async revokeTokens(payload) {
+    return;
+  }
+}

package/src/plugins/identity/drivers/client-credentials-driver.js

@@ -0,0 +1,127 @@
+import { AuthDriver } from './auth-driver.interface.js';
+import { PluginError } from '../../../errors.js';
+import { tryFn } from '../../../concerns/try-fn.js';
+
+function constantTimeEqual(a, b) {
+  const valueA = Buffer.from(String(a ?? ''), 'utf8');
+  const valueB = Buffer.from(String(b ?? ''), 'utf8');
+
+  if (valueA.length !== valueB.length) {
+    return false;
+  }
+
+  let mismatch = 0;
+  for (let i = 0; i < valueA.length; i += 1) {
+    mismatch |= valueA[i] ^ valueB[i];
+  }
+  return mismatch === 0;
+}
+
+export class ClientCredentialsAuthDriver extends AuthDriver {
+  constructor(options = {}) {
+    super('client-credentials', ['client_credentials']);
+    this.options = options;
+    this.clientResource = null;
+    this.passwordHelper = null;
+  }
+
+  async initialize(context) {
+    this.clientResource = context.resources?.clients;
+    if (!this.clientResource) {
+      throw new PluginError('ClientCredentialsAuthDriver requires clients resource', {
+        pluginName: 'IdentityPlugin',
+        operation: 'initializeClientCredentialsDriver',
+        statusCode: 500,
+        retriable: false,
+        suggestion: 'Map a clients resource in IdentityPlugin resources before enabling client credentials authentication.'
+      });
+    }
+    this.passwordHelper = context.helpers?.password || null;
+  }
+
+  supportsGrant(grantType) {
+    return grantType === 'client_credentials';
+  }
+
+  async authenticate(request) {
+    const { clientId, clientSecret } = request;
+    if (!clientId || !clientSecret) {
+      return { success: false, error: 'invalid_client', statusCode: 401 };
+    }
+
+    const [ok, err, clients] = await tryFn(() => this.clientResource.query({ clientId }));
+    if (!ok) {
+      return {
+        success: false,
+        error: err?.message || 'lookup_failed',
+        statusCode: 500
+      };
+    }
+
+    if (!clients || clients.length === 0) {
+      return { success: false, error: 'invalid_client', statusCode: 401 };
+    }
+
+    const client = clients[0];
+
+    if (client.active === false) {
+      return { success: false, error: 'inactive_client', statusCode: 403 };
+    }
+
+    const secrets = [];
+    if (Array.isArray(client.secrets)) {
+      secrets.push(...client.secrets);
+    }
+    if (client.clientSecret) {
+      secrets.push(client.clientSecret);
+    }
+    if (client.secret) {
+      secrets.push(client.secret);
+    }
+
+    if (!secrets.length) {
+      return { success: false, error: 'invalid_client', statusCode: 401 };
+    }
+
+    const secretMatches = await this._verifyAgainstSecrets(clientSecret, secrets);
+    if (!secretMatches) {
+      return { success: false, error: 'invalid_client', statusCode: 401 };
+    }
+
+    const sanitizedClient = { ...client };
+    if (sanitizedClient.clientSecret !== undefined) {
+      delete sanitizedClient.clientSecret;
+    }
+    if (sanitizedClient.secret !== undefined) {
+      delete sanitizedClient.secret;
+    }
+    if (sanitizedClient.secrets !== undefined) {
+      delete sanitizedClient.secrets;
+    }
+
+    return {
+      success: true,
+      client: sanitizedClient
+    };
+  }
+
+  async _verifyAgainstSecrets(providedSecret, storedSecrets) {
+    for (const storedSecret of storedSecrets) {
+      if (!storedSecret) continue;
+
+      if (typeof storedSecret === 'string' && storedSecret.startsWith('$') && this.passwordHelper?.verify) {
+        const ok = await this.passwordHelper.verify(providedSecret, storedSecret);
+        if (ok) {
+          return true;
+        }
+        continue;
+      }
+
+      if (constantTimeEqual(providedSecret, storedSecret)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+}

package/src/plugins/identity/drivers/index.js

@@ -0,0 +1,18 @@
+import { PasswordAuthDriver } from './password-driver.js';
+import { ClientCredentialsAuthDriver } from './client-credentials-driver.js';
+
+export function createBuiltInAuthDrivers(options = {}) {
+  const drivers = [];
+
+  if (options.disablePassword !== true) {
+    drivers.push(new PasswordAuthDriver(options.password || {}));
+  }
+
+  if (options.disableClientCredentials !== true) {
+    drivers.push(new ClientCredentialsAuthDriver(options.clientCredentials || {}));
+  }
+
+  return drivers;
+}
+
+export { PasswordAuthDriver, ClientCredentialsAuthDriver };