@qwickapps/server 1.4.0 → 1.5.0

package/src/plugins/parental/parental-plugin.ts

@@ -0,0 +1,759 @@
+/**
+ * Parental Plugin
+ *
+ * Generic parental/guardian controls for @qwickapps/server.
+ * Supports PIN protection, profile restrictions, schedules, and activity logging.
+ * Uses adapters for domain-specific behavior (kids, gaming, education).
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { createHash } from 'crypto';
+import type { Request, Response } from 'express';
+import type { Plugin, PluginConfig, PluginRegistry } from '../../core/plugin-registry.js';
+import type {
+  ParentalPluginConfig,
+  ParentalStore,
+  ParentalAdapter,
+  GuardianSettings,
+  ProfileRestriction,
+  ActivityLog,
+  AccessCheckResult,
+  CreateGuardianSettingsInput,
+  UpdateGuardianSettingsInput,
+  CreateRestrictionInput,
+  LogActivityInput,
+} from './types.js';
+
+// Store instances for helper access
+let currentStore: ParentalStore | null = null;
+let currentAdapter: ParentalAdapter | null = null;
+let currentConfig: ParentalPluginConfig | null = null;
+
+/**
+ * Hash a PIN using SHA-256
+ */
+function hashPin(pin: string): string {
+  return createHash('sha256').update(pin).digest('hex');
+}
+
+/**
+ * Check if current time is within allowed schedule
+ */
+function isWithinSchedule(schedule: Record<string, { start: string; end: string }>): boolean {
+  const now = new Date();
+  const dayNames = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
+  const today = dayNames[now.getDay()];
+
+  const todaySchedule = schedule[today];
+  if (!todaySchedule) return true; // No schedule for today = allowed
+
+  const currentTime = `${now.getHours().toString().padStart(2, '0')}:${now.getMinutes().toString().padStart(2, '0')}`;
+
+  return currentTime >= todaySchedule.start && currentTime <= todaySchedule.end;
+}
+
+/**
+ * Create the Parental plugin
+ */
+export function createParentalPlugin(config: ParentalPluginConfig): Plugin {
+  const debug = config.debug || false;
+  const apiPrefix = config.api?.prefix || '/parental';
+  const maxPinAttempts = config.maxPinAttempts || 5;
+  const pinLockoutMinutes = config.pinLockoutMinutes || 30;
+
+  function log(message: string, data?: Record<string, unknown>) {
+    if (debug) {
+      console.log(`[ParentalPlugin] ${message}`, data || '');
+    }
+  }
+
+  return {
+    id: 'parental',
+    name: 'Parental',
+    version: '1.0.0',
+
+    async onStart(_pluginConfig: PluginConfig, registry: PluginRegistry): Promise<void> {
+      log('Starting parental plugin');
+
+      // Initialize the store (creates tables if needed)
+      await config.store.initialize();
+      log('Parental store initialized');
+
+      // Store references for helper access
+      currentStore = config.store;
+      currentAdapter = config.adapter;
+      currentConfig = config;
+
+      // Register health check
+      registry.registerHealthCheck({
+        name: 'parental-store',
+        type: 'custom',
+        check: async () => {
+          try {
+            return { healthy: true };
+          } catch {
+            return { healthy: false };
+          }
+        },
+      });
+
+      // Add API routes if enabled
+      if (config.api?.enabled !== false) {
+        // ═══════════════════════════════════════════════════════════════════════
+        // Guardian Settings Routes
+        // ═══════════════════════════════════════════════════════════════════════
+
+        // Get guardian settings
+        registry.addRoute({
+          method: 'get',
+          path: `${apiPrefix}/settings/:userId`,
+          pluginId: 'parental',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const { userId } = req.params;
+              const settings = await getGuardianSettings(userId);
+
+              if (!settings) {
+                return res.status(404).json({ error: 'Settings not found' });
+              }
+
+              // Don't expose PIN hash
+              const { pin_hash: _pin, ...safeSettings } = settings;
+              res.json({ ...safeSettings, has_pin: !!_pin });
+            } catch (error) {
+              console.error('[ParentalPlugin] Get settings error:', error);
+              res.status(500).json({ error: 'Failed to get settings' });
+            }
+          },
+        });
+
+        // Create guardian settings
+        registry.addRoute({
+          method: 'post',
+          path: `${apiPrefix}/settings`,
+          pluginId: 'parental',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const input = req.body as CreateGuardianSettingsInput;
+
+              // Hash PIN if provided
+              const processedInput = {
+                ...input,
+                adapter_type: config.adapter.name,
+                pin: input.pin ? hashPin(input.pin) : undefined,
+              };
+
+              const settings = await createGuardianSettings(processedInput);
+              const { pin_hash: _pin, ...safeSettings } = settings;
+              res.status(201).json({ ...safeSettings, has_pin: !!_pin });
+            } catch (error) {
+              console.error('[ParentalPlugin] Create settings error:', error);
+              res.status(500).json({ error: 'Failed to create settings' });
+            }
+          },
+        });
+
+        // Update guardian settings
+        registry.addRoute({
+          method: 'patch',
+          path: `${apiPrefix}/settings/:userId`,
+          pluginId: 'parental',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const { userId } = req.params;
+              const input = req.body as UpdateGuardianSettingsInput;
+
+              const settings = await updateGuardianSettings(userId, input);
+              if (!settings) {
+                return res.status(404).json({ error: 'Settings not found' });
+              }
+
+              const { pin_hash: _pin, ...safeSettings } = settings;
+              res.json({ ...safeSettings, has_pin: !!_pin });
+            } catch (error) {
+              console.error('[ParentalPlugin] Update settings error:', error);
+              res.status(500).json({ error: 'Failed to update settings' });
+            }
+          },
+        });
+
+        // Set PIN
+        registry.addRoute({
+          method: 'post',
+          path: `${apiPrefix}/settings/:userId/pin`,
+          pluginId: 'parental',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const { userId } = req.params;
+              const { pin, current_pin } = req.body;
+
+              if (!pin || pin.length < 4) {
+                return res.status(400).json({ error: 'PIN must be at least 4 characters' });
+              }
+
+              // If user already has PIN, verify current PIN
+              const settings = await getGuardianSettings(userId);
+              if (settings?.pin_hash) {
+                if (!current_pin) {
+                  return res.status(400).json({ error: 'Current PIN required to change PIN' });
+                }
+                const isValid = await verifyPin(userId, current_pin);
+                if (!isValid) {
+                  return res.status(401).json({ error: 'Invalid current PIN' });
+                }
+              }
+
+              await setPin(userId, pin);
+              res.json({ success: true });
+            } catch (error) {
+              console.error('[ParentalPlugin] Set PIN error:', error);
+              res.status(500).json({ error: 'Failed to set PIN' });
+            }
+          },
+        });
+
+        // Verify PIN
+        registry.addRoute({
+          method: 'post',
+          path: `${apiPrefix}/settings/:userId/verify-pin`,
+          pluginId: 'parental',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const { userId } = req.params;
+              const { pin } = req.body;
+
+              if (!pin) {
+                return res.status(400).json({ error: 'PIN required' });
+              }
+
+              const isValid = await verifyPin(userId, pin);
+
+              if (!isValid) {
+                // Increment failed attempts
+                const attempts = await incrementFailedPinAttempts(userId);
+
+                if (attempts >= maxPinAttempts) {
+                  // Lock the account
+                  const lockUntil = new Date(Date.now() + pinLockoutMinutes * 60 * 1000);
+                  return res.status(423).json({
+                    error: 'Account locked due to too many failed attempts',
+                    locked_until: lockUntil,
+                    attempts,
+                  });
+                }
+
+                return res.status(401).json({
+                  error: 'Invalid PIN',
+                  attempts_remaining: maxPinAttempts - attempts,
+                });
+              }
+
+              // Reset failed attempts on success
+              await resetFailedPinAttempts(userId);
+              res.json({ success: true });
+            } catch (error) {
+              console.error('[ParentalPlugin] Verify PIN error:', error);
+              res.status(500).json({ error: 'Failed to verify PIN' });
+            }
+          },
+        });
+
+        // ═══════════════════════════════════════════════════════════════════════
+        // Profile Restrictions Routes
+        // ═══════════════════════════════════════════════════════════════════════
+
+        // Get restrictions for a profile
+        registry.addRoute({
+          method: 'get',
+          path: `${apiPrefix}/restrictions/:profileId`,
+          pluginId: 'parental',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const { profileId } = req.params;
+              const restrictions = await getRestrictions(profileId);
+              res.json(restrictions);
+            } catch (error) {
+              console.error('[ParentalPlugin] Get restrictions error:', error);
+              res.status(500).json({ error: 'Failed to get restrictions' });
+            }
+          },
+        });
+
+        // Create restriction
+        registry.addRoute({
+          method: 'post',
+          path: `${apiPrefix}/restrictions`,
+          pluginId: 'parental',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const input = req.body as CreateRestrictionInput;
+
+              // Validate with adapter
+              if (config.adapter.validateRestriction) {
+                const validation = config.adapter.validateRestriction(input);
+                if (!validation.valid) {
+                  return res.status(400).json({ error: 'Invalid restriction', errors: validation.errors });
+                }
+              }
+
+              const restriction = await createRestriction(input);
+              res.status(201).json(restriction);
+            } catch (error) {
+              console.error('[ParentalPlugin] Create restriction error:', error);
+              res.status(500).json({ error: 'Failed to create restriction' });
+            }
+          },
+        });
+
+        // Update restriction
+        registry.addRoute({
+          method: 'patch',
+          path: `${apiPrefix}/restrictions/:id`,
+          pluginId: 'parental',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const { id } = req.params;
+              const updates = req.body as Partial<ProfileRestriction>;
+
+              const restriction = await updateRestriction(id, updates);
+              if (!restriction) {
+                return res.status(404).json({ error: 'Restriction not found' });
+              }
+              res.json(restriction);
+            } catch (error) {
+              console.error('[ParentalPlugin] Update restriction error:', error);
+              res.status(500).json({ error: 'Failed to update restriction' });
+            }
+          },
+        });
+
+        // Delete restriction
+        registry.addRoute({
+          method: 'delete',
+          path: `${apiPrefix}/restrictions/:id`,
+          pluginId: 'parental',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const { id } = req.params;
+              const deleted = await deleteRestriction(id);
+
+              if (!deleted) {
+                return res.status(404).json({ error: 'Restriction not found' });
+              }
+              res.status(204).send();
+            } catch (error) {
+              console.error('[ParentalPlugin] Delete restriction error:', error);
+              res.status(500).json({ error: 'Failed to delete restriction' });
+            }
+          },
+        });
+
+        // Pause profile
+        registry.addRoute({
+          method: 'post',
+          path: `${apiPrefix}/restrictions/:profileId/pause`,
+          pluginId: 'parental',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const { profileId } = req.params;
+              const { until, reason } = req.body;
+
+              await pauseProfile(profileId, until ? new Date(until) : undefined, reason);
+              res.json({ success: true, paused: true });
+            } catch (error) {
+              console.error('[ParentalPlugin] Pause profile error:', error);
+              res.status(500).json({ error: 'Failed to pause profile' });
+            }
+          },
+        });
+
+        // Resume profile
+        registry.addRoute({
+          method: 'post',
+          path: `${apiPrefix}/restrictions/:profileId/resume`,
+          pluginId: 'parental',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const { profileId } = req.params;
+              await resumeProfile(profileId);
+              res.json({ success: true, paused: false });
+            } catch (error) {
+              console.error('[ParentalPlugin] Resume profile error:', error);
+              res.status(500).json({ error: 'Failed to resume profile' });
+            }
+          },
+        });
+
+        // Check profile access
+        registry.addRoute({
+          method: 'get',
+          path: `${apiPrefix}/restrictions/:profileId/check`,
+          pluginId: 'parental',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const { profileId } = req.params;
+              const result = await checkProfileAccess(profileId);
+              res.json(result);
+            } catch (error) {
+              console.error('[ParentalPlugin] Check access error:', error);
+              res.status(500).json({ error: 'Failed to check access' });
+            }
+          },
+        });
+
+        // ═══════════════════════════════════════════════════════════════════════
+        // Activity Log Routes
+        // ═══════════════════════════════════════════════════════════════════════
+
+        // Log activity
+        registry.addRoute({
+          method: 'post',
+          path: `${apiPrefix}/activity`,
+          pluginId: 'parental',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const input = req.body as LogActivityInput;
+              const activity = await logActivity({
+                ...input,
+                adapter_type: config.adapter.name,
+              });
+              res.status(201).json(activity);
+            } catch (error) {
+              console.error('[ParentalPlugin] Log activity error:', error);
+              res.status(500).json({ error: 'Failed to log activity' });
+            }
+          },
+        });
+
+        // Get activity log
+        registry.addRoute({
+          method: 'get',
+          path: `${apiPrefix}/activity/:userId`,
+          pluginId: 'parental',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const { userId } = req.params;
+              const limit = parseInt(req.query.limit as string) || 100;
+              const profileId = req.query.profileId as string | undefined;
+
+              const activities = await getActivityLog(userId, limit, profileId);
+
+              // Format details with adapter if available
+              const formattedActivities = activities.map((activity) => {
+                if (config.adapter.formatActivityDetails) {
+                  return {
+                    ...activity,
+                    formatted_details: config.adapter.formatActivityDetails(activity),
+                  };
+                }
+                return activity;
+              });
+
+              res.json(formattedActivities);
+            } catch (error) {
+              console.error('[ParentalPlugin] Get activity error:', error);
+              res.status(500).json({ error: 'Failed to get activity log' });
+            }
+          },
+        });
+
+        // Get adapter info (activity types, defaults)
+        registry.addRoute({
+          method: 'get',
+          path: `${apiPrefix}/adapter-info`,
+          pluginId: 'parental',
+          handler: async (_req: Request, res: Response) => {
+            try {
+              res.json({
+                name: config.adapter.name,
+                activity_types: config.adapter.getActivityTypes(),
+                default_daily_limit: config.adapter.getDefaultDailyLimit(),
+              });
+            } catch (error) {
+              console.error('[ParentalPlugin] Get adapter info error:', error);
+              res.status(500).json({ error: 'Failed to get adapter info' });
+            }
+          },
+        });
+      }
+
+      log('Parental plugin started');
+    },
+
+    async onStop(): Promise<void> {
+      log('Stopping parental plugin');
+      await config.store.shutdown();
+      currentStore = null;
+      currentAdapter = null;
+      currentConfig = null;
+      log('Parental plugin stopped');
+    },
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Helper Functions
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Get the current parental store instance
+ */
+export function getParentalStore(): ParentalStore | null {
+  return currentStore;
+}
+
+/**
+ * Get the current parental adapter instance
+ */
+export function getParentalAdapter(): ParentalAdapter | null {
+  return currentAdapter;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Guardian Settings Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Get guardian settings for a user
+ */
+export async function getGuardianSettings(userId: string): Promise<GuardianSettings | null> {
+  if (!currentStore) {
+    throw new Error('Parental plugin not initialized');
+  }
+  return currentStore.getSettings(userId);
+}
+
+/**
+ * Create guardian settings
+ */
+export async function createGuardianSettings(input: CreateGuardianSettingsInput): Promise<GuardianSettings> {
+  if (!currentStore) {
+    throw new Error('Parental plugin not initialized');
+  }
+  return currentStore.createSettings(input);
+}
+
+/**
+ * Update guardian settings
+ */
+export async function updateGuardianSettings(
+  userId: string,
+  input: UpdateGuardianSettingsInput
+): Promise<GuardianSettings | null> {
+  if (!currentStore) {
+    throw new Error('Parental plugin not initialized');
+  }
+  return currentStore.updateSettings(userId, input);
+}
+
+/**
+ * Set PIN for guardian
+ */
+export async function setPin(userId: string, pin: string): Promise<void> {
+  if (!currentStore) {
+    throw new Error('Parental plugin not initialized');
+  }
+  const pinHash = hashPin(pin);
+  return currentStore.setPin(userId, pinHash);
+}
+
+/**
+ * Verify PIN
+ */
+export async function verifyPin(userId: string, pin: string): Promise<boolean> {
+  if (!currentStore) {
+    throw new Error('Parental plugin not initialized');
+  }
+  const pinHash = hashPin(pin);
+  return currentStore.verifyPin(userId, pinHash);
+}
+
+/**
+ * Increment failed PIN attempts
+ */
+export async function incrementFailedPinAttempts(userId: string): Promise<number> {
+  if (!currentStore) {
+    throw new Error('Parental plugin not initialized');
+  }
+  return currentStore.incrementFailedPinAttempts(userId);
+}
+
+/**
+ * Reset failed PIN attempts
+ */
+export async function resetFailedPinAttempts(userId: string): Promise<void> {
+  if (!currentStore) {
+    throw new Error('Parental plugin not initialized');
+  }
+  return currentStore.resetFailedPinAttempts(userId);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Profile Restrictions Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Get restrictions for a profile
+ */
+export async function getRestrictions(profileId: string): Promise<ProfileRestriction[]> {
+  if (!currentStore) {
+    throw new Error('Parental plugin not initialized');
+  }
+  return currentStore.getRestrictions(profileId);
+}
+
+/**
+ * Create a restriction
+ */
+export async function createRestriction(input: CreateRestrictionInput): Promise<ProfileRestriction> {
+  if (!currentStore) {
+    throw new Error('Parental plugin not initialized');
+  }
+  return currentStore.createRestriction(input);
+}
+
+/**
+ * Update a restriction
+ */
+export async function updateRestriction(
+  id: string,
+  updates: Partial<ProfileRestriction>
+): Promise<ProfileRestriction | null> {
+  if (!currentStore) {
+    throw new Error('Parental plugin not initialized');
+  }
+  return currentStore.updateRestriction(id, updates);
+}
+
+/**
+ * Delete a restriction (soft delete)
+ */
+export async function deleteRestriction(id: string): Promise<boolean> {
+  if (!currentStore) {
+    throw new Error('Parental plugin not initialized');
+  }
+  return currentStore.deleteRestriction(id);
+}
+
+/**
+ * Pause a profile's access
+ */
+export async function pauseProfile(profileId: string, until?: Date, reason?: string): Promise<void> {
+  if (!currentStore) {
+    throw new Error('Parental plugin not initialized');
+  }
+  return currentStore.pauseProfile(profileId, until, reason);
+}
+
+/**
+ * Resume a profile's access
+ */
+export async function resumeProfile(profileId: string): Promise<void> {
+  if (!currentStore) {
+    throw new Error('Parental plugin not initialized');
+  }
+  return currentStore.resumeProfile(profileId);
+}
+
+/**
+ * Check if a profile has access based on restrictions
+ */
+export async function checkProfileAccess(profileId: string): Promise<AccessCheckResult> {
+  if (!currentStore) {
+    throw new Error('Parental plugin not initialized');
+  }
+
+  const restrictions = await currentStore.getRestrictions(profileId);
+
+  // Check if any restrictions are paused
+  for (const restriction of restrictions) {
+    if (restriction.is_paused) {
+      // Check if pause has expired
+      if (restriction.pause_until && new Date() > restriction.pause_until) {
+        // Auto-resume (should be handled by cron, but check here too)
+        continue;
+      }
+      return {
+        allowed: false,
+        reason: restriction.pause_reason || 'Profile is paused',
+      };
+    }
+
+    // Check schedule restrictions
+    if (restriction.schedule) {
+      if (!isWithinSchedule(restriction.schedule)) {
+        // Find when access becomes available
+        const now = new Date();
+        const dayNames = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
+        const today = dayNames[now.getDay()];
+        const todaySchedule = restriction.schedule[today];
+
+        let availableAt: Date | undefined;
+        if (todaySchedule) {
+          const [hours, minutes] = todaySchedule.start.split(':').map(Number);
+          availableAt = new Date(now);
+          availableAt.setHours(hours, minutes, 0, 0);
+
+          // If we're past today's start, set to tomorrow
+          if (now > availableAt) {
+            availableAt.setDate(availableAt.getDate() + 1);
+          }
+        }
+
+        return {
+          allowed: false,
+          reason: 'Outside allowed hours',
+          available_at: availableAt,
+        };
+      }
+    }
+  }
+
+  // Get time limit restriction and check remaining time
+  const timeLimitRestriction = restrictions.find((r) => r.restriction_type === 'time_limit');
+  if (timeLimitRestriction?.daily_limit_minutes) {
+    // Note: Actual time tracking would be done via usage-plugin
+    // This is a placeholder for the check result
+    return {
+      allowed: true,
+      minutes_remaining: timeLimitRestriction.daily_limit_minutes,
+    };
+  }
+
+  return { allowed: true };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Activity Log Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Log an activity
+ */
+export async function logActivity(input: LogActivityInput): Promise<ActivityLog> {
+  if (!currentStore) {
+    throw new Error('Parental plugin not initialized');
+  }
+
+  // Call adapter hook if available
+  if (currentAdapter?.onRestrictionViolation && input.activity_type === 'restriction_violation') {
+    await currentAdapter.onRestrictionViolation(input.profile_id || '', input.details?.reason as string || 'Unknown');
+  }
+
+  if (currentAdapter?.onDailyLimitReached && input.activity_type === 'time_limit_reached') {
+    await currentAdapter.onDailyLimitReached(input.profile_id || '');
+  }
+
+  return currentStore.logActivity(input);
+}
+
+/**
+ * Get activity log
+ */
+export async function getActivityLog(userId: string, limit = 100, profileId?: string): Promise<ActivityLog[]> {
+  if (!currentStore) {
+    throw new Error('Parental plugin not initialized');
+  }
+  return currentStore.getActivityLog(userId, limit, profileId);
+}