s3db.js 13.4.0 → 13.6.0

package/src/plugins/concerns/plugin-dependencies.js

@@ -107,6 +107,60 @@ export const PLUGIN_DEPENDENCIES = {
         description: 'Swagger UI integration for Hono',
         installCommand: 'pnpm add @hono/swagger-ui',
         npmUrl: 'https://www.npmjs.com/package/@hono/swagger-ui'
+      },
+      'jose': {
+        version: '^5.0.0 || ^6.0.0',
+        description: 'Universal JOSE and JWE implementation (for OAuth2 token validation)',
+        installCommand: 'pnpm add jose',
+        npmUrl: 'https://www.npmjs.com/package/jose'
+      }
+    }
+  },
+  'identity-plugin': {
+    name: 'Identity Provider Plugin',
+    docsUrl: 'https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/identity.md',
+    dependencies: {
+      'hono': {
+        version: '^4.0.0',
+        description: 'Ultra-light HTTP server framework',
+        installCommand: 'pnpm add hono',
+        npmUrl: 'https://www.npmjs.com/package/hono'
+      },
+      '@hono/node-server': {
+        version: '^1.0.0',
+        description: 'Node.js adapter for Hono',
+        installCommand: 'pnpm add @hono/node-server',
+        npmUrl: 'https://www.npmjs.com/package/@hono/node-server'
+      },
+      'jose': {
+        version: '^5.0.0 || ^6.0.0',
+        description: 'Universal JOSE and JWE implementation (for RSA key generation and JWT signing)',
+        installCommand: 'pnpm add jose',
+        npmUrl: 'https://www.npmjs.com/package/jose'
+      },
+      'bcrypt': {
+        version: '^5.1.0 || ^6.0.0',
+        description: 'Secure password hashing library',
+        installCommand: 'pnpm add bcrypt',
+        npmUrl: 'https://www.npmjs.com/package/bcrypt'
+      },
+      'nodemailer': {
+        version: '^6.9.0 || ^7.0.0',
+        description: 'Email sending library for password reset and verification',
+        installCommand: 'pnpm add nodemailer',
+        npmUrl: 'https://www.npmjs.com/package/nodemailer'
+      }
+    }
+  },
+  'cloud-inventory-plugin': {
+    name: 'Cloud Inventory Plugin',
+    docsUrl: 'https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/cloud-inventory.md',
+    dependencies: {
+      'node-cron': {
+        version: '^4.0.0',
+        description: 'Cron scheduler for automated discovery',
+        installCommand: 'pnpm add -D node-cron',
+        npmUrl: 'https://www.npmjs.com/package/node-cron'
       }
     }
   },
@@ -127,12 +181,18 @@ export const PLUGIN_DEPENDENCIES = {
 /**
  * Simple semver comparison for major version checking
  * @param {string} actual - Actual version (e.g., "8.11.3")
- * @param {string} required - Required version range (e.g., "^8.0.0")
+ * @param {string} required - Required version range (e.g., "^8.0.0" or "^5.0.0 || ^6.0.0")
  * @returns {boolean} True if version is compatible
  */
 function isVersionCompatible(actual, required) {
   if (!actual || !required) return false;
 
+  // Handle OR operators (||)
+  if (required.includes('||')) {
+    const ranges = required.split('||').map(r => r.trim());
+    return ranges.some(range => isVersionCompatible(actual, range));
+  }
+
   // Remove ^ and ~ prefixes
   const cleanRequired = required.replace(/^[\^~]/, '');
 
@@ -170,7 +230,7 @@ async function tryLoadPackage(packageName) {
     let version = null;
     try {
       const pkgJson = await import(`${packageName}/package.json`, {
-        assert: { type: 'json' }
+        with: { type: 'json' }
       });
       version = pkgJson.default?.version || pkgJson.version || null;
     } catch (e) {

package/src/plugins/eventual-consistency/analytics.js

@@ -1196,6 +1196,7 @@ export async function getLastNMonths(resourceName, field, months = 12, options,
     const dataMap = new Map(data.map(d => [d.cohort, d]));
 
     const current = new Date(monthsAgo);
+    current.setDate(1); // Set to 1st of month to avoid day overflow bugs
     for (let i = 0; i < months; i++) {
       const cohort = current.toISOString().substring(0, 7);
       result.push(dataMap.get(cohort) || { cohort, ...emptyRecord });

package/src/plugins/eventual-consistency/consolidation.js

@@ -140,7 +140,7 @@ export async function runConsolidation(transactionResource, consolidateRecordFn,
     }
 
     if (emitFn) {
-      emitFn('eventual-consistency.consolidated', {
+      emitFn('plg:eventual-consistency:consolidated', {
         resource: config.resource,
         field: config.field,
         recordCount: uniqueIds.length,
@@ -157,7 +157,7 @@ export async function runConsolidation(transactionResource, consolidateRecordFn,
       error
     );
     if (emitFn) {
-      emitFn('eventual-consistency.consolidation-error', error);
+      emitFn('plg:eventual-consistency:consolidation-error', error);
     }
   }
 }

package/src/plugins/eventual-consistency/garbage-collection.js

@@ -103,7 +103,7 @@ export async function runGarbageCollection(transactionResource, storage, config,
     }
 
     if (emitFn) {
-      emitFn('eventual-consistency.gc-completed', {
+      emitFn('plg:eventual-consistency:gc-completed', {
         resource: config.resource,
         field: config.field,
         deletedCount: results.length,
@@ -115,7 +115,7 @@ export async function runGarbageCollection(transactionResource, storage, config,
       console.warn(`[EventualConsistency] GC error:`, error.message);
     }
     if (emitFn) {
-      emitFn('eventual-consistency.gc-error', error);
+      emitFn('plg:eventual-consistency:gc-error', error);
     }
   } finally {
     // Always release GC lock

package/src/plugins/eventual-consistency/install.js

@@ -255,7 +255,7 @@ export async function onStart(fieldHandlers, config, runConsolidationFn, runGCFn
         }
 
         if (emitFn) {
-          emitFn('eventual-consistency.started', {
+          emitFn('plg:eventual-consistency:started', {
             resource: resourceName,
             field: fieldName,
             cohort: config.cohort
@@ -295,7 +295,7 @@ export async function onStop(fieldHandlers, emitFn) {
       }
 
       if (emitFn) {
-        emitFn('eventual-consistency.stopped', {
+        emitFn('plg:eventual-consistency:stopped', {
           resource: resourceName,
           field: fieldName
         });

package/src/plugins/identity/README.md

@@ -0,0 +1,335 @@
+# Identity Provider Plugin
+
+Complete OAuth2/OpenID Connect Identity Provider for S3DB.
+
+## Quick Start
+
+```javascript
+import { Database } from 's3db.js';
+import { IdentityPlugin } from 's3db.js/plugins/identity';
+
+const db = new Database({
+  connectionString: 'http://minioadmin:minioadmin@localhost:9000/myapp'
+});
+
+await db.initialize();
+
+const identityPlugin = new IdentityPlugin({
+  issuer: 'http://localhost:4000',
+  database: db
+});
+
+await identityPlugin.initialize();
+```
+
+Access at: http://localhost:4000/login
+
+## Features
+
+✅ **Complete Authentication System**
+- Login/Logout with session management
+- User registration with email verification
+- Password reset flow
+- Profile management
+
+✅ **OAuth2/OpenID Connect Server**
+- Authorization code flow with PKCE
+- Client credentials flow
+- Refresh token support
+- Full OIDC compliance
+
+✅ **Admin Panel**
+- User management (CRUD, status, roles)
+- OAuth2 client management
+- Session monitoring
+
+✅ **100% White-Label UI**
+- 30+ theme customization options (colors, fonts, logos)
+- **Custom CSS injection** - Poder total para customização
+- Tailwind 4 CDN - Classes utilitárias prontas
+- Custom page overrides
+- Responsive design
+- Social media integration
+
+✅ **Registration Controls**
+- Enable/disable public registration
+- Email domain whitelist/blacklist
+- Email verification requirement
+
+✅ **Security**
+- bcrypt password hashing
+- Configurable password policy
+- Session management with device tracking
+- CSRF protection
+
+## Documentation
+
+- **[Complete Documentation](../../../docs/plugins/identity-plugin.md)** - Full guide with all features
+- **[Configuration Reference](../../../docs/plugins/identity-config-reference.md)** - All configuration options
+- **[White-Label Guide](../../../docs/plugins/identity/WHITELABEL.md)** - 🎨 Complete branding customization guide
+- **[Examples Index](../../../docs/plugins/identity-examples.md)** - Example code and use cases
+
+## Examples
+
+| Example | Description |
+|---------|-------------|
+| `e85-identity-whitelabel.js` | S3dbCorp complete white-label branding |
+| `e86-custom-login-page.js` | Custom login page with HTML override |
+| `e87-identity-no-registration.js` | Disabled public registration |
+
+Run examples:
+```bash
+node docs/examples/e85-identity-whitelabel.js
+```
+
+## Basic Configuration
+
+### Minimal Setup
+
+```javascript
+new IdentityPlugin({
+  issuer: 'http://localhost:4000',
+  database: db
+})
+```
+
+### Production Setup
+
+```javascript
+new IdentityPlugin({
+  issuer: 'https://auth.company.com',
+  database: db,
+
+  registration: {
+    enabled: true,
+    requireEmailVerification: true,
+    allowedDomains: ['company.com']
+  },
+
+  passwordPolicy: {
+    minLength: 12,
+    requireSymbols: true,
+    bcryptRounds: 12
+  },
+
+  session: {
+    sessionExpiry: '8h',
+    cookieSecure: true,
+    cookieSameSite: 'Strict'
+  },
+
+  email: {
+    enabled: true,
+    smtp: {
+      host: process.env.SMTP_HOST,
+      port: 587,
+      auth: {
+        user: process.env.SMTP_USER,
+        pass: process.env.SMTP_PASS
+      }
+    }
+  },
+
+  ui: {
+    companyName: 'My Company',
+    primaryColor: '#0066CC',
+    logoUrl: 'https://company.com/logo.svg'
+  }
+})
+```
+
+## Access Points
+
+After starting the server:
+
+- **Login**: `/login`
+- **Register**: `/register`
+- **Profile**: `/profile` (requires login)
+- **Admin**: `/admin` (requires admin role)
+- **OIDC Discovery**: `/.well-known/openid-configuration`
+- **JWKS**: `/.well-known/jwks.json`
+
+## OAuth2 Endpoints
+
+- `GET /oauth/authorize` - Authorization (consent screen)
+- `POST /oauth/token` - Token exchange
+- `GET /oauth/userinfo` - OIDC UserInfo
+- `POST /oauth/introspect` - Token introspection
+- `POST /oauth/revoke` - Token revocation
+- `POST /oauth/register` - Client registration
+
+## Admin Panel
+
+Create admin user:
+
+```javascript
+const usersResource = db.resources.users;
+
+await usersResource.insert({
+  email: 'admin@example.com',
+  name: 'Admin User',
+  passwordHash: await hashPassword('SecurePass123!'),
+  status: 'active',
+  emailVerified: true,
+  role: 'admin'
+});
+```
+
+Access admin panel at `/admin` after login.
+
+## White-Label Customization
+
+### Basic Branding
+
+```javascript
+ui: {
+  companyName: 'Acme Corp',
+  tagline: 'Secure Cloud Solutions',
+  logoUrl: 'https://acme.com/logo.svg',
+  primaryColor: '#ff6600',
+  supportEmail: 'support@acme.com'
+}
+```
+
+### Custom Pages
+
+```javascript
+import { html } from 'hono/html';
+
+function MyCustomLoginPage(props) {
+  const { error, email, config } = props;
+
+  return html`<!DOCTYPE html>
+    <html>
+      <head><title>Login - ${config.companyName}</title></head>
+      <body>
+        <form method="POST" action="/login">
+          <input type="email" name="email" value="${email}" />
+          <input type="password" name="password" />
+          <button>Sign In</button>
+        </form>
+      </body>
+    </html>`;
+}
+
+ui: {
+  customPages: {
+    login: MyCustomLoginPage
+  }
+}
+```
+
+## Registration Controls
+
+### Disable Public Registration
+
+```javascript
+registration: {
+  enabled: false,
+  customMessage: 'Contact admin for access'
+}
+```
+
+### Corporate Emails Only
+
+```javascript
+registration: {
+  enabled: true,
+  allowedDomains: ['company.com', 'partner.com']
+}
+```
+
+### Block Temporary Emails
+
+```javascript
+registration: {
+  enabled: true,
+  blockedDomains: ['tempmail.com', 'guerrillamail.com']
+}
+```
+
+## Architecture
+
+```
+Identity Plugin
+├── OAuth2/OIDC Server (authorization, tokens, PKCE)
+├── UI Pages (login, register, profile, admin)
+├── Session Manager (cookie-based sessions)
+├── Email Service (SMTP integration)
+└── S3DB Resources
+    ├── plg_oauth_keys (RSA keys)
+    ├── plg_oauth_clients (registered clients)
+    ├── plg_auth_codes (authorization codes)
+    ├── plg_sessions (user sessions)
+    ├── plg_password_reset_tokens (reset tokens)
+    └── users (user accounts)
+```
+
+## Security Best Practices
+
+1. **Use HTTPS in production**
+   ```javascript
+   session: { cookieSecure: true },
+   server: { security: { hsts: true } }
+   ```
+
+2. **Strong password policy**
+   ```javascript
+   passwordPolicy: {
+     minLength: 12,
+     requireSymbols: true,
+     bcryptRounds: 12
+   }
+   ```
+
+3. **Email verification required**
+   ```javascript
+   registration: { requireEmailVerification: true }
+   ```
+
+4. **Restrict origins**
+   ```javascript
+   server: {
+     cors: { origin: ['https://app.company.com'] }
+   }
+   ```
+
+## Troubleshooting
+
+### Session not persisting
+
+Check cookie settings match deployment (HTTP vs HTTPS):
+```javascript
+session: {
+  cookieSecure: false,  // Development (HTTP)
+  // cookieSecure: true,  // Production (HTTPS)
+}
+```
+
+### Email not sending
+
+Test SMTP connection:
+```bash
+# Use MailHog for testing
+docker run -d -p 1025:1025 -p 8025:8025 mailhog/mailhog
+
+SMTP_HOST=localhost SMTP_PORT=1025 node your-app.js
+```
+
+### Admin panel not accessible
+
+User needs admin role:
+```javascript
+await usersResource.update(userId, { role: 'admin' });
+```
+
+## Resources
+
+- [Full Documentation](../../../docs/plugins/identity-plugin.md)
+- [Configuration Reference](../../../docs/plugins/identity-config-reference.md)
+- [Examples](../../../docs/plugins/identity-examples.md)
+- [S3DB Documentation](../../../README.md)
+
+## License
+
+MIT

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

@@ -0,0 +1,204 @@
+/**
+ * MFA Manager - Multi-Factor Authentication for Identity Plugin
+ *
+ * Handles TOTP (Time-based One-Time Password) generation, verification,
+ * and backup codes management.
+ *
+ * Compatible with: Google Authenticator, Authy, Microsoft Authenticator, 1Password
+ *
+ * @example
+ * import { MFAManager } from './concerns/mfa-manager.js';
+ *
+ * const mfaManager = new MFAManager({
+ *   issuer: 'MyApp',
+ *   algorithm: 'SHA1',
+ *   digits: 6,
+ *   period: 30
+ * });
+ *
+ * // Enroll user
+ * const enrollment = await mfaManager.generateEnrollment('user@example.com');
+ * console.log(enrollment.qrCodeUrl);  // Display QR code
+ * console.log(enrollment.secret);     // Manual entry key
+ *
+ * // Verify TOTP token
+ * const isValid = mfaManager.verifyTOTP(enrollment.secret, '123456');
+ *
+ * // Generate backup codes
+ * const backupCodes = mfaManager.generateBackupCodes(10);
+ */
+
+import { requirePluginDependency } from '../../concerns/plugin-dependencies.js';
+import { idGenerator } from '../../../concerns/id.js';
+
+export class MFAManager {
+  constructor(options = {}) {
+    this.options = {
+      issuer: options.issuer || 'S3DB Identity',
+      algorithm: options.algorithm || 'SHA1',      // SHA1, SHA256, SHA512
+      digits: options.digits || 6,                 // 6 or 8 digits
+      period: options.period || 30,                // 30 seconds
+      window: options.window || 1,                 // Allow ±1 time step (90s total)
+      backupCodesCount: options.backupCodesCount || 10,
+      backupCodeLength: options.backupCodeLength || 8
+    };
+
+    this.OTPAuth = null;
+  }
+
+  /**
+   * Initialize MFA Manager (load otpauth library)
+   */
+  async initialize() {
+    this.OTPAuth = await requirePluginDependency(
+      'otpauth',
+      'IdentityPlugin (MFA)',
+      'Multi-Factor Authentication'
+    );
+  }
+
+  /**
+   * Generate MFA enrollment data for a user
+   * @param {string} accountName - User email or username
+   * @returns {Object} Enrollment data with secret, QR code URL, and backup codes
+   */
+  generateEnrollment(accountName) {
+    if (!this.OTPAuth) {
+      throw new Error('[MFA] OTPAuth library not initialized');
+    }
+
+    // Generate TOTP secret
+    const totp = new this.OTPAuth.TOTP({
+      issuer: this.options.issuer,
+      label: accountName,
+      algorithm: this.options.algorithm,
+      digits: this.options.digits,
+      period: this.options.period,
+      secret: this.OTPAuth.Secret.fromBase32(
+        this.OTPAuth.Secret.generate().base32
+      )
+    });
+
+    // Generate QR code URL
+    const qrCodeUrl = totp.toString();
+
+    // Generate backup codes
+    const backupCodes = this.generateBackupCodes(this.options.backupCodesCount);
+
+    return {
+      secret: totp.secret.base32,           // For manual entry
+      qrCodeUrl,                            // For QR code scanning
+      backupCodes,                          // Emergency access codes
+      algorithm: this.options.algorithm,
+      digits: this.options.digits,
+      period: this.options.period
+    };
+  }
+
+  /**
+   * Verify a TOTP token
+   * @param {string} secret - Base32 encoded secret
+   * @param {string} token - 6-digit token from authenticator app
+   * @returns {boolean} True if valid
+   */
+  verifyTOTP(secret, token) {
+    if (!this.OTPAuth) {
+      throw new Error('[MFA] OTPAuth library not initialized');
+    }
+
+    try {
+      const totp = new this.OTPAuth.TOTP({
+        issuer: this.options.issuer,
+        algorithm: this.options.algorithm,
+        digits: this.options.digits,
+        period: this.options.period,
+        secret: this.OTPAuth.Secret.fromBase32(secret)
+      });
+
+      // Validate token with time window
+      const delta = totp.validate({
+        token,
+        window: this.options.window
+      });
+
+      // delta is null if invalid, or number if valid
+      return delta !== null;
+    } catch (error) {
+      console.error('[MFA] TOTP verification error:', error.message);
+      return false;
+    }
+  }
+
+  /**
+   * Generate backup codes for emergency access
+   * @param {number} count - Number of codes to generate
+   * @returns {Array<string>} Array of backup codes
+   */
+  generateBackupCodes(count = 10) {
+    const codes = [];
+    const length = this.options.backupCodeLength;
+
+    for (let i = 0; i < count; i++) {
+      // Generate random alphanumeric code
+      const code = idGenerator()
+        .replace(/[^a-zA-Z0-9]/g, '')
+        .substring(0, length)
+        .toUpperCase();
+
+      codes.push(code);
+    }
+
+    return codes;
+  }
+
+  /**
+   * Hash backup codes for storage
+   * @param {Array<string>} codes - Backup codes
+   * @returns {Array<string>} Hashed codes
+   */
+  async hashBackupCodes(codes) {
+    const crypto = await import('crypto');
+    return codes.map(code => {
+      return crypto.createHash('sha256')
+        .update(code)
+        .digest('hex');
+    });
+  }
+
+  /**
+   * Verify a backup code
+   * @param {string} code - Backup code to verify
+   * @param {Array<string>} hashedCodes - Array of hashed backup codes
+   * @returns {number|null} Index of matched code, or null if not found
+   */
+  async verifyBackupCode(code, hashedCodes) {
+    const crypto = await import('crypto');
+    const hashedInput = crypto.createHash('sha256')
+      .update(code.toUpperCase())
+      .digest('hex');
+
+    return hashedCodes.findIndex(hash => hash === hashedInput);
+  }
+
+  /**
+   * Generate QR code data URL for display
+   * @param {string} qrCodeUrl - OTP auth URL
+   * @returns {Promise<string>} Data URL for QR code image
+   */
+  async generateQRCodeDataURL(qrCodeUrl) {
+    try {
+      const QRCode = await requirePluginDependency(
+        'qrcode',
+        'IdentityPlugin (MFA)',
+        'QR code generation for MFA enrollment'
+      );
+
+      return await QRCode.toDataURL(qrCodeUrl);
+    } catch (error) {
+      console.error('[MFA] QR code generation error:', error.message);
+      return null;
+    }
+  }
+}
+
+export default MFAManager;