s3db.js 13.4.0 → 13.6.0

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

@@ -0,0 +1,138 @@
+/**
+ * Password Management - Validation and Generation
+ *
+ * Uses S3DB native 'password' type for one-way bcrypt hashing.
+ * Passwords are hashed automatically on insert/update using bcrypt.
+ * Provides password strength validation according to policy.
+ */
+
+import { verifyPassword as bcryptVerify } from '../../../concerns/password-hashing.js';
+
+/**
+ * Default password policy
+ */
+const DEFAULT_PASSWORD_POLICY = {
+  minLength: 8,
+  maxLength: 128,
+  requireUppercase: true,
+  requireLowercase: true,
+  requireNumbers: true,
+  requireSymbols: false
+};
+
+/**
+ * Verify a plaintext password against a stored bcrypt hash
+ *
+ * NOTE: With S3DB's `password` type, passwords are auto-hashed on insert/update
+ * using bcrypt with compaction (60 → 53 bytes). This function verifies the
+ * plaintext password against the stored hash using bcrypt.compare().
+ *
+ * @param {string} plaintext - Plaintext password to verify
+ * @param {string} storedHash - Stored bcrypt hash (compacted, 53 bytes)
+ * @returns {Promise<boolean>} True if password matches, false otherwise
+ */
+export async function verifyPassword(plaintext, storedHash) {
+  // Use bcrypt verification from password-hashing.js
+  // It handles both full (60 bytes) and compacted (53 bytes) hashes
+  return await bcryptVerify(plaintext, storedHash);
+}
+
+/**
+ * Validate password against policy
+ * @param {string} password - Password to validate
+ * @param {Object} [policy=DEFAULT_PASSWORD_POLICY] - Password policy rules
+ * @returns {{valid: boolean, errors: string[]}} Validation result
+ */
+export function validatePassword(password, policy = DEFAULT_PASSWORD_POLICY) {
+  const errors = [];
+
+  if (!password || typeof password !== 'string') {
+    return { valid: false, errors: ['Password must be a string'] };
+  }
+
+  // Merge with defaults
+  const rules = { ...DEFAULT_PASSWORD_POLICY, ...policy };
+
+  // Length checks
+  if (password.length < rules.minLength) {
+    errors.push(`Password must be at least ${rules.minLength} characters long`);
+  }
+
+  if (password.length > rules.maxLength) {
+    errors.push(`Password must not exceed ${rules.maxLength} characters`);
+  }
+
+  // Character type checks
+  if (rules.requireUppercase && !/[A-Z]/.test(password)) {
+    errors.push('Password must contain at least one uppercase letter');
+  }
+
+  if (rules.requireLowercase && !/[a-z]/.test(password)) {
+    errors.push('Password must contain at least one lowercase letter');
+  }
+
+  if (rules.requireNumbers && !/[0-9]/.test(password)) {
+    errors.push('Password must contain at least one number');
+  }
+
+  if (rules.requireSymbols && !/[!@#$%^&*()_+\-=\[\]{};':"\\|,.<>\/?]/.test(password)) {
+    errors.push('Password must contain at least one symbol');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Generate a random password that meets policy requirements
+ * @param {Object} [policy=DEFAULT_PASSWORD_POLICY] - Password policy rules
+ * @returns {string} Generated password
+ */
+export function generatePassword(policy = DEFAULT_PASSWORD_POLICY) {
+  const rules = { ...DEFAULT_PASSWORD_POLICY, ...policy };
+
+  const lowercase = 'abcdefghijklmnopqrstuvwxyz';
+  const uppercase = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+  const numbers = '0123456789';
+  const symbols = '!@#$%^&*()_+-=[]{};\':"|,.<>/?';
+
+  let chars = '';
+  let password = '';
+
+  // Always include lowercase
+  chars += lowercase;
+  password += lowercase[Math.floor(Math.random() * lowercase.length)];
+
+  if (rules.requireUppercase) {
+    chars += uppercase;
+    password += uppercase[Math.floor(Math.random() * uppercase.length)];
+  }
+
+  if (rules.requireNumbers) {
+    chars += numbers;
+    password += numbers[Math.floor(Math.random() * numbers.length)];
+  }
+
+  if (rules.requireSymbols) {
+    chars += symbols;
+    password += symbols[Math.floor(Math.random() * symbols.length)];
+  }
+
+  // Fill remaining length with random characters from allowed set
+  const remaining = rules.minLength - password.length;
+  for (let i = 0; i < remaining; i++) {
+    password += chars[Math.floor(Math.random() * chars.length)];
+  }
+
+  // Shuffle password
+  return password.split('').sort(() => Math.random() - 0.5).join('');
+}
+
+export default {
+  verifyPassword,
+  validatePassword,
+  generatePassword,
+  DEFAULT_PASSWORD_POLICY
+};

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

@@ -0,0 +1,273 @@
+/**
+ * Resource Schema Definitions - Base attributes for Identity Plugin resources
+ *
+ * These are the REQUIRED attributes that the Identity Plugin needs to function.
+ * Users can extend these with custom attributes, but cannot override base fields.
+ */
+
+/**
+ * Base attributes for Users resource
+ *
+ * Required by Identity Plugin for authentication and authorization
+ */
+export const BASE_USER_ATTRIBUTES = {
+  // Authentication
+  email: 'string|required|email',
+  password: 'password|required',
+  emailVerified: 'boolean|default:false',
+
+  // Profile
+  name: 'string|optional',
+  givenName: 'string|optional',
+  familyName: 'string|optional',
+  nickname: 'string|optional',
+  picture: 'string|optional',
+  locale: 'string|optional',
+
+  // Authorization
+  scopes: 'array|items:string|optional',
+  roles: 'array|items:string|optional',
+
+  // Multi-tenancy
+  tenantId: 'string|optional',  // Tenant the user belongs to
+
+  // Status
+  active: 'boolean|default:true',
+
+  // Account Lockout (Brute Force Protection)
+  failedLoginAttempts: 'number|default:0',      // Count of failed login attempts
+  lockedUntil: 'string|optional',               // ISO timestamp when account unlocks
+  lastFailedLogin: 'string|optional',           // ISO timestamp of last failed attempt
+
+  // Metadata
+  metadata: 'object|optional'
+};
+
+/**
+ * Base attributes for Tenants resource
+ *
+ * Required by Identity Plugin for multi-tenancy support
+ */
+export const BASE_TENANT_ATTRIBUTES = {
+  // Identity
+  name: 'string|required',
+  slug: 'string|required',  // URL-friendly identifier
+
+  // Settings
+  settings: 'object|optional',
+
+  // Status
+  active: 'boolean|default:true',
+
+  // Metadata
+  metadata: 'object|optional'
+};
+
+/**
+ * Base attributes for OAuth2 Clients resource
+ *
+ * Required by Identity Plugin for OAuth2/OIDC flows
+ */
+export const BASE_CLIENT_ATTRIBUTES = {
+  // OAuth2 Identity
+  clientId: 'string|required',
+  clientSecret: 'secret|required',
+
+  // Client Info
+  name: 'string|required',
+  description: 'string|optional',
+
+  // OAuth2 Configuration
+  redirectUris: 'array|items:string|required',
+  allowedScopes: 'array|items:string|optional',
+  grantTypes: 'array|items:string|default:["authorization_code","refresh_token"]',
+  responseTypes: 'array|items:string|optional',
+
+  // Multi-tenancy
+  tenantId: 'string|optional',  // Tenant the client belongs to
+
+  // Security
+  tokenEndpointAuthMethod: 'string|default:client_secret_post',
+  requirePkce: 'boolean|default:false',
+
+  // Status
+  active: 'boolean|default:true',
+
+  // Metadata
+  metadata: 'object|optional'
+};
+
+/**
+ * Deep merge two objects
+ * @param {Object} target - Target object
+ * @param {Object} source - Source object
+ * @returns {Object} Merged object
+ */
+function deepMerge(target, source) {
+  const output = { ...target };
+
+  for (const key in source) {
+    if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
+      if (target[key] && typeof target[key] === 'object' && !Array.isArray(target[key])) {
+        output[key] = deepMerge(target[key], source[key]);
+      } else {
+        output[key] = source[key];
+      }
+    } else {
+      output[key] = source[key];
+    }
+  }
+
+  return output;
+}
+
+/**
+ * Validate that user-provided attributes don't conflict with base attributes
+ * and that optional fields have defaults
+ *
+ * @param {Object} baseAttributes - Base attributes from plugin
+ * @param {Object} userAttributes - User-provided extra attributes
+ * @param {string} resourceType - Type of resource (for error messages)
+ * @returns {Object} result - { valid: boolean, errors: string[] }
+ */
+export function validateExtraAttributes(baseAttributes, userAttributes, resourceType) {
+  const errors = [];
+
+  if (!userAttributes || typeof userAttributes !== 'object') {
+    return { valid: true, errors: [] };  // No extras = valid
+  }
+
+  // Check for conflicts with base attributes
+  for (const fieldName of Object.keys(userAttributes)) {
+    if (baseAttributes[fieldName]) {
+      errors.push(
+        `Cannot override base attribute '${fieldName}' in ${resourceType} resource. ` +
+        `Base attributes are managed by IdentityPlugin.`
+      );
+    }
+  }
+
+  // Check that optional fields have defaults
+  for (const [fieldName, fieldSchema] of Object.entries(userAttributes)) {
+    const isOptional = typeof fieldSchema === 'string' && fieldSchema.includes('optional');
+    const hasDefault = typeof fieldSchema === 'string' && fieldSchema.includes('default:');
+
+    if (isOptional && !hasDefault) {
+      errors.push(
+        `Extra attribute '${fieldName}' in ${resourceType} resource is optional but has no default value. ` +
+        `Add "|default:value" to the schema or make it required.`
+      );
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Merge base resource config with user-provided config (deep merge)
+ *
+ * @param {Object} baseConfig - Base resource config from plugin
+ * @param {Object} userConfig - User-provided resource config
+ * @param {string} resourceType - Type of resource (for error messages)
+ * @returns {Object} mergedConfig - Combined resource configuration
+ * @throws {Error} If validation fails
+ */
+export function mergeResourceConfig(baseConfig, userConfig = {}, resourceType) {
+  // Validate user attributes if provided
+  if (userConfig.attributes) {
+    const validation = validateExtraAttributes(
+      baseConfig.attributes,
+      userConfig.attributes,
+      resourceType
+    );
+
+    if (!validation.valid) {
+      const errorMsg = [
+        `Invalid extra attributes for ${resourceType} resource:`,
+        ...validation.errors.map(err => `  - ${err}`)
+      ].join('\n');
+      throw new Error(errorMsg);
+    }
+  }
+
+  // Deep merge: user config first, then base config (base takes precedence)
+  const merged = deepMerge(userConfig, baseConfig);
+
+  // Merge attributes specially to ensure base attributes are preserved
+  if (userConfig.attributes || baseConfig.attributes) {
+    merged.attributes = {
+      ...(userConfig.attributes || {}),  // User extras first
+      ...(baseConfig.attributes || {})   // Base overrides (protection)
+    };
+  }
+
+  return merged;
+}
+
+/**
+ * Validate required resource configuration from user
+ *
+ * @param {Object} resourcesConfig - User-provided resources configuration
+ * @returns {Object} result - { valid: boolean, errors: string[] }
+ */
+export function validateResourcesConfig(resourcesConfig) {
+  const errors = [];
+
+  if (!resourcesConfig || typeof resourcesConfig !== 'object') {
+    errors.push('IdentityPlugin requires "resources" configuration object');
+    return { valid: false, errors };
+  }
+
+  // Validate users resource
+  if (!resourcesConfig.users) {
+    errors.push(
+      'IdentityPlugin requires "resources.users" configuration.\n' +
+      'Example: resources: { users: { name: "users", attributes: {...}, hooks: {...} } }'
+    );
+  } else {
+    if (!resourcesConfig.users.name || typeof resourcesConfig.users.name !== 'string') {
+      errors.push('resources.users.name is required and must be a string');
+    }
+  }
+
+  // Validate tenants resource
+  if (!resourcesConfig.tenants) {
+    errors.push(
+      'IdentityPlugin requires "resources.tenants" configuration.\n' +
+      'Example: resources: { tenants: { name: "tenants", attributes: {...}, partitions: {...} } }'
+    );
+  } else {
+    if (!resourcesConfig.tenants.name || typeof resourcesConfig.tenants.name !== 'string') {
+      errors.push('resources.tenants.name is required and must be a string');
+    }
+  }
+
+  // Validate clients resource
+  if (!resourcesConfig.clients) {
+    errors.push(
+      'IdentityPlugin requires "resources.clients" configuration.\n' +
+      'Example: resources: { clients: { name: "oauth_clients", attributes: {...}, behavior: "..." } }'
+    );
+  } else {
+    if (!resourcesConfig.clients.name || typeof resourcesConfig.clients.name !== 'string') {
+      errors.push('resources.clients.name is required and must be a string');
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+export default {
+  BASE_USER_ATTRIBUTES,
+  BASE_TENANT_ATTRIBUTES,
+  BASE_CLIENT_ATTRIBUTES,
+  validateExtraAttributes,
+  mergeResourceConfig,
+  validateResourcesConfig
+};

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

@@ -0,0 +1,172 @@
+/**
+ * Secure Token Generator
+ *
+ * Generates cryptographically secure random tokens for various use cases:
+ * - Password reset tokens
+ * - Email verification tokens
+ * - API tokens
+ * - Session IDs
+ */
+
+import { randomBytes } from 'crypto';
+import { idGenerator } from '../../../concerns/id.js';
+
+/**
+ * Generate a secure random token
+ * @param {number} [bytes=32] - Number of random bytes (default: 32 bytes = 256 bits)
+ * @param {string} [encoding='hex'] - Output encoding ('hex', 'base64', 'base64url')
+ * @returns {string} Random token
+ */
+export function generateToken(bytes = 32, encoding = 'hex') {
+  const buffer = randomBytes(bytes);
+
+  switch (encoding) {
+    case 'hex':
+      return buffer.toString('hex');
+
+    case 'base64':
+      return buffer.toString('base64');
+
+    case 'base64url':
+      return buffer.toString('base64url');
+
+    default:
+      throw new Error(`Invalid encoding: ${encoding}. Use 'hex', 'base64', or 'base64url'.`);
+  }
+}
+
+/**
+ * Generate a password reset token (URL-safe)
+ * @returns {string} 64-character hex token (32 bytes)
+ */
+export function generatePasswordResetToken() {
+  return generateToken(32, 'hex');
+}
+
+/**
+ * Generate an email verification token (URL-safe)
+ * @returns {string} 64-character hex token (32 bytes)
+ */
+export function generateEmailVerificationToken() {
+  return generateToken(32, 'hex');
+}
+
+/**
+ * Generate a session ID using nanoid
+ * @returns {string} 22-character session ID
+ */
+export function generateSessionId() {
+  return idGenerator();
+}
+
+/**
+ * Generate an API key (longer, more secure)
+ * @returns {string} 64-character hex API key (32 bytes)
+ */
+export function generateAPIKey() {
+  return generateToken(32, 'hex');
+}
+
+/**
+ * Generate a short numeric code (for 2FA, OTP, etc.)
+ * @param {number} [length=6] - Number of digits (default: 6)
+ * @returns {string} Numeric code (e.g., "123456")
+ */
+export function generateNumericCode(length = 6) {
+  const max = Math.pow(10, length);
+  const min = Math.pow(10, length - 1);
+
+  // Generate random number in range [min, max)
+  const randomNum = Math.floor(min + Math.random() * (max - min));
+
+  return randomNum.toString().padStart(length, '0');
+}
+
+/**
+ * Generate a short alphanumeric code (for invite codes, etc.)
+ * @param {number} [length=8] - Number of characters (default: 8)
+ * @returns {string} Alphanumeric code (e.g., "A3B7K9M2")
+ */
+export function generateAlphanumericCode(length = 8) {
+  const chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'; // Excludes similar chars (I, O, 0, 1)
+  let code = '';
+
+  const buffer = randomBytes(length);
+
+  for (let i = 0; i < length; i++) {
+    code += chars[buffer[i] % chars.length];
+  }
+
+  return code;
+}
+
+/**
+ * Generate a CSRF token (medium security)
+ * @returns {string} 32-character hex CSRF token (16 bytes)
+ */
+export function generateCSRFToken() {
+  return generateToken(16, 'hex');
+}
+
+/**
+ * Calculate expiration timestamp
+ * @param {string|number} duration - Duration string ('15m', '1h', '7d') or milliseconds
+ * @returns {number} Unix timestamp (milliseconds)
+ */
+export function calculateExpiration(duration) {
+  let ms;
+
+  if (typeof duration === 'number') {
+    ms = duration;
+  } else if (typeof duration === 'string') {
+    const match = duration.match(/^(\d+)([smhd])$/);
+
+    if (!match) {
+      throw new Error(`Invalid duration format: ${duration}. Use '15m', '1h', '7d', etc.`);
+    }
+
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+
+    switch (unit) {
+      case 's': ms = value * 1000; break;           // seconds
+      case 'm': ms = value * 60 * 1000; break;      // minutes
+      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}`);
+    }
+  } else {
+    throw new Error('Duration must be a string or number');
+  }
+
+  return Date.now() + ms;
+}
+
+/**
+ * Check if token/timestamp is expired
+ * @param {number|string} expiresAt - Expiration timestamp (Unix ms) or ISO string
+ * @returns {boolean} True if expired, false otherwise
+ */
+export function isExpired(expiresAt) {
+  if (!expiresAt) {
+    return true;
+  }
+
+  const timestamp = typeof expiresAt === 'string' ? new Date(expiresAt).getTime() : expiresAt;
+
+  return Date.now() > timestamp;
+}
+
+export default {
+  generateToken,
+  generatePasswordResetToken,
+  generateEmailVerificationToken,
+  generateSessionId,
+  generateAPIKey,
+  generateNumericCode,
+  generateAlphanumericCode,
+  generateCSRFToken,
+  calculateExpiration,
+  isExpired
+};