@qwickapps/server 1.3.1 → 1.5.0

package/src/plugins/parental/stores/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Parental Stores
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+export { postgresParentalStore } from './postgres-store.js';

package/src/plugins/parental/stores/postgres-store.ts

@@ -0,0 +1,304 @@
+/**
+ * PostgreSQL Parental Store
+ *
+ * Parental controls storage implementation using PostgreSQL.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type {
+  ParentalStore,
+  GuardianSettings,
+  ProfileRestriction,
+  ActivityLog,
+  CreateGuardianSettingsInput,
+  UpdateGuardianSettingsInput,
+  CreateRestrictionInput,
+  LogActivityInput,
+  PostgresParentalStoreConfig,
+} from '../types.js';
+
+interface PgPool {
+  query(text: string, values?: unknown[]): Promise<{ rows: unknown[]; rowCount: number | null }>;
+}
+
+export function postgresParentalStore(config: PostgresParentalStoreConfig): ParentalStore {
+  const {
+    pool: poolOrFn,
+    settingsTable = 'guardian_settings',
+    restrictionsTable = 'profile_restrictions',
+    activityTable = 'activity_log',
+    schema = 'public',
+    autoCreateTables = true,
+  } = config;
+
+  const getPool = (): PgPool => {
+    const pool = typeof poolOrFn === 'function' ? poolOrFn() : poolOrFn;
+    return pool as PgPool;
+  };
+
+  const settingsFull = `"${schema}"."${settingsTable}"`;
+  const restrictionsFull = `"${schema}"."${restrictionsTable}"`;
+  const activityFull = `"${schema}"."${activityTable}"`;
+
+  return {
+    name: 'postgres',
+
+    async initialize(): Promise<void> {
+      if (!autoCreateTables) return;
+
+      await getPool().query(`
+        CREATE TABLE IF NOT EXISTS ${settingsFull} (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          user_id UUID UNIQUE NOT NULL,
+          adapter_type VARCHAR(50) NOT NULL,
+          pin_hash VARCHAR(64),
+          pin_failed_attempts INTEGER DEFAULT 0,
+          pin_locked_until TIMESTAMPTZ,
+          biometric_enabled BOOLEAN DEFAULT false,
+          notifications_enabled BOOLEAN DEFAULT true,
+          weekly_report_enabled BOOLEAN DEFAULT true,
+          metadata JSONB DEFAULT '{}',
+          updated_at TIMESTAMPTZ DEFAULT NOW()
+        );
+        CREATE INDEX IF NOT EXISTS idx_${settingsTable}_user ON ${settingsFull}(user_id);
+      `);
+
+      await getPool().query(`
+        CREATE TABLE IF NOT EXISTS ${restrictionsFull} (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          profile_id UUID NOT NULL,
+          restriction_type VARCHAR(50) NOT NULL,
+          daily_limit_minutes INTEGER,
+          schedule JSONB,
+          is_paused BOOLEAN DEFAULT false,
+          pause_until TIMESTAMPTZ,
+          pause_reason TEXT,
+          is_active BOOLEAN DEFAULT true,
+          metadata JSONB DEFAULT '{}',
+          updated_at TIMESTAMPTZ DEFAULT NOW()
+        );
+        CREATE INDEX IF NOT EXISTS idx_${restrictionsTable}_profile ON ${restrictionsFull}(profile_id);
+      `);
+
+      await getPool().query(`
+        CREATE TABLE IF NOT EXISTS ${activityFull} (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          user_id UUID NOT NULL,
+          profile_id UUID,
+          device_id UUID,
+          adapter_type VARCHAR(50) NOT NULL,
+          activity_type VARCHAR(50) NOT NULL,
+          details JSONB DEFAULT '{}',
+          created_at TIMESTAMPTZ DEFAULT NOW()
+        );
+        CREATE INDEX IF NOT EXISTS idx_${activityTable}_user_profile ON ${activityFull}(user_id, profile_id);
+        CREATE INDEX IF NOT EXISTS idx_${activityTable}_created ON ${activityFull}(created_at DESC);
+      `);
+    },
+
+    async getSettings(userId: string): Promise<GuardianSettings | null> {
+      const result = await getPool().query(
+        `SELECT * FROM ${settingsFull} WHERE user_id = $1`,
+        [userId]
+      );
+      return (result.rows[0] as GuardianSettings) || null;
+    },
+
+    async createSettings(input: CreateGuardianSettingsInput): Promise<GuardianSettings> {
+      const result = await getPool().query(
+        `INSERT INTO ${settingsFull} (user_id, adapter_type, pin_hash, biometric_enabled, notifications_enabled, weekly_report_enabled, metadata)
+         VALUES ($1, $2, $3, $4, $5, $6, $7)
+         RETURNING *`,
+        [
+          input.user_id,
+          input.adapter_type,
+          input.pin || null,
+          input.biometric_enabled || false,
+          input.notifications_enabled !== false,
+          input.weekly_report_enabled !== false,
+          JSON.stringify(input.metadata || {}),
+        ]
+      );
+      return result.rows[0] as GuardianSettings;
+    },
+
+    async updateSettings(userId: string, input: UpdateGuardianSettingsInput): Promise<GuardianSettings | null> {
+      const updates: string[] = [];
+      const values: unknown[] = [];
+      let idx = 1;
+
+      if (input.biometric_enabled !== undefined) {
+        updates.push(`biometric_enabled = $${idx++}`);
+        values.push(input.biometric_enabled);
+      }
+      if (input.notifications_enabled !== undefined) {
+        updates.push(`notifications_enabled = $${idx++}`);
+        values.push(input.notifications_enabled);
+      }
+      if (input.weekly_report_enabled !== undefined) {
+        updates.push(`weekly_report_enabled = $${idx++}`);
+        values.push(input.weekly_report_enabled);
+      }
+      if (input.metadata !== undefined) {
+        updates.push(`metadata = $${idx++}`);
+        values.push(JSON.stringify(input.metadata));
+      }
+
+      if (updates.length === 0) return this.getSettings(userId);
+
+      updates.push('updated_at = NOW()');
+      values.push(userId);
+
+      const result = await getPool().query(
+        `UPDATE ${settingsFull} SET ${updates.join(', ')} WHERE user_id = $${idx} RETURNING *`,
+        values
+      );
+      return (result.rows[0] as GuardianSettings) || null;
+    },
+
+    async setPin(userId: string, pinHash: string): Promise<void> {
+      await getPool().query(
+        `UPDATE ${settingsFull} SET pin_hash = $1, pin_failed_attempts = 0, pin_locked_until = NULL, updated_at = NOW() WHERE user_id = $2`,
+        [pinHash, userId]
+      );
+    },
+
+    async verifyPin(userId: string, pinHash: string): Promise<boolean> {
+      const result = await getPool().query(
+        `SELECT pin_hash, pin_locked_until FROM ${settingsFull} WHERE user_id = $1`,
+        [userId]
+      );
+      if (!result.rows[0]) return false;
+
+      const settings = result.rows[0] as { pin_hash: string | null; pin_locked_until: Date | null };
+      if (settings.pin_locked_until && new Date() < settings.pin_locked_until) return false;
+
+      return settings.pin_hash === pinHash;
+    },
+
+    async incrementFailedPinAttempts(userId: string): Promise<number> {
+      const result = await getPool().query(
+        `UPDATE ${settingsFull} SET pin_failed_attempts = pin_failed_attempts + 1, updated_at = NOW()
+         WHERE user_id = $1 RETURNING pin_failed_attempts`,
+        [userId]
+      );
+      return (result.rows[0] as { pin_failed_attempts: number })?.pin_failed_attempts || 0;
+    },
+
+    async resetFailedPinAttempts(userId: string): Promise<void> {
+      await getPool().query(
+        `UPDATE ${settingsFull} SET pin_failed_attempts = 0, pin_locked_until = NULL, updated_at = NOW() WHERE user_id = $1`,
+        [userId]
+      );
+    },
+
+    async getRestrictions(profileId: string): Promise<ProfileRestriction[]> {
+      const result = await getPool().query(
+        `SELECT * FROM ${restrictionsFull} WHERE profile_id = $1 AND is_active = true`,
+        [profileId]
+      );
+      return result.rows as ProfileRestriction[];
+    },
+
+    async createRestriction(input: CreateRestrictionInput): Promise<ProfileRestriction> {
+      const result = await getPool().query(
+        `INSERT INTO ${restrictionsFull} (profile_id, restriction_type, daily_limit_minutes, schedule, metadata)
+         VALUES ($1, $2, $3, $4, $5)
+         RETURNING *`,
+        [
+          input.profile_id,
+          input.restriction_type,
+          input.daily_limit_minutes || null,
+          input.schedule ? JSON.stringify(input.schedule) : null,
+          JSON.stringify(input.metadata || {}),
+        ]
+      );
+      return result.rows[0] as ProfileRestriction;
+    },
+
+    async updateRestriction(id: string, updates: Partial<ProfileRestriction>): Promise<ProfileRestriction | null> {
+      const setClause: string[] = [];
+      const values: unknown[] = [];
+      let idx = 1;
+
+      const allowedFields = ['daily_limit_minutes', 'schedule', 'is_paused', 'pause_until', 'pause_reason', 'is_active', 'metadata'];
+      for (const field of allowedFields) {
+        if (updates[field as keyof ProfileRestriction] !== undefined) {
+          setClause.push(`${field} = $${idx++}`);
+          const val = updates[field as keyof ProfileRestriction];
+          values.push(field === 'schedule' || field === 'metadata' ? JSON.stringify(val) : val);
+        }
+      }
+
+      if (setClause.length === 0) return null;
+      setClause.push('updated_at = NOW()');
+      values.push(id);
+
+      const result = await getPool().query(
+        `UPDATE ${restrictionsFull} SET ${setClause.join(', ')} WHERE id = $${idx} RETURNING *`,
+        values
+      );
+      return (result.rows[0] as ProfileRestriction) || null;
+    },
+
+    async deleteRestriction(id: string): Promise<boolean> {
+      const result = await getPool().query(
+        `UPDATE ${restrictionsFull} SET is_active = false, updated_at = NOW() WHERE id = $1`,
+        [id]
+      );
+      return (result.rowCount ?? 0) > 0;
+    },
+
+    async pauseProfile(profileId: string, until?: Date, reason?: string): Promise<void> {
+      await getPool().query(
+        `UPDATE ${restrictionsFull} SET is_paused = true, pause_until = $2, pause_reason = $3, updated_at = NOW()
+         WHERE profile_id = $1 AND is_active = true`,
+        [profileId, until || null, reason || null]
+      );
+    },
+
+    async resumeProfile(profileId: string): Promise<void> {
+      await getPool().query(
+        `UPDATE ${restrictionsFull} SET is_paused = false, pause_until = NULL, pause_reason = NULL, updated_at = NOW()
+         WHERE profile_id = $1`,
+        [profileId]
+      );
+    },
+
+    async logActivity(input: LogActivityInput): Promise<ActivityLog> {
+      const result = await getPool().query(
+        `INSERT INTO ${activityFull} (user_id, profile_id, device_id, adapter_type, activity_type, details)
+         VALUES ($1, $2, $3, $4, $5, $6)
+         RETURNING *`,
+        [
+          input.user_id,
+          input.profile_id || null,
+          input.device_id || null,
+          input.adapter_type,
+          input.activity_type,
+          JSON.stringify(input.details || {}),
+        ]
+      );
+      return result.rows[0] as ActivityLog;
+    },
+
+    async getActivityLog(userId: string, limit = 100, profileId?: string): Promise<ActivityLog[]> {
+      let query = `SELECT * FROM ${activityFull} WHERE user_id = $1`;
+      const values: unknown[] = [userId];
+
+      if (profileId) {
+        query += ` AND profile_id = $2`;
+        values.push(profileId);
+      }
+
+      query += ` ORDER BY created_at DESC LIMIT $${values.length + 1}`;
+      values.push(limit);
+
+      const result = await getPool().query(query, values);
+      return result.rows as ActivityLog[];
+    },
+
+    async shutdown(): Promise<void> {},
+  };
+}

package/src/plugins/parental/types.ts

@@ -0,0 +1,180 @@
+/**
+ * Parental Plugin Types
+ *
+ * Type definitions for parental/guardian controls with adapter support.
+ * Supports different use cases through adapters (kids, gaming, education).
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+/**
+ * Guardian settings for a user
+ */
+export interface GuardianSettings {
+  id: string;
+  user_id: string;
+  adapter_type: string;
+  pin_hash?: string;
+  pin_failed_attempts: number;
+  pin_locked_until?: Date;
+  biometric_enabled: boolean;
+  notifications_enabled: boolean;
+  weekly_report_enabled: boolean;
+  metadata: Record<string, unknown>;
+  updated_at: Date;
+}
+
+/**
+ * Profile restriction
+ */
+export interface ProfileRestriction {
+  id: string;
+  profile_id: string;
+  restriction_type: string;
+  daily_limit_minutes?: number;
+  schedule?: Record<string, { start: string; end: string }>;
+  is_paused: boolean;
+  pause_until?: Date;
+  pause_reason?: string;
+  is_active: boolean;
+  metadata: Record<string, unknown>;
+  updated_at: Date;
+}
+
+/**
+ * Activity log entry
+ */
+export interface ActivityLog {
+  id: string;
+  user_id: string;
+  profile_id?: string;
+  device_id?: string;
+  adapter_type: string;
+  activity_type: string;
+  details: Record<string, unknown>;
+  created_at: Date;
+}
+
+/**
+ * Access check result
+ */
+export interface AccessCheckResult {
+  allowed: boolean;
+  reason?: string;
+  minutes_remaining?: number;
+  available_at?: Date;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Input Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface CreateGuardianSettingsInput {
+  user_id: string;
+  adapter_type: string;
+  pin?: string;
+  biometric_enabled?: boolean;
+  notifications_enabled?: boolean;
+  weekly_report_enabled?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+export interface UpdateGuardianSettingsInput {
+  biometric_enabled?: boolean;
+  notifications_enabled?: boolean;
+  weekly_report_enabled?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CreateRestrictionInput {
+  profile_id: string;
+  restriction_type: string;
+  daily_limit_minutes?: number;
+  schedule?: Record<string, { start: string; end: string }>;
+  metadata?: Record<string, unknown>;
+}
+
+export interface LogActivityInput {
+  user_id: string;
+  profile_id?: string;
+  device_id?: string;
+  adapter_type: string;
+  activity_type: string;
+  details?: Record<string, unknown>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Adapter Interface
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Parental adapter interface
+ */
+export interface ParentalAdapter {
+  name: string;
+  getActivityTypes(): string[];
+  getDefaultDailyLimit(): number;
+  validateRestriction?(restriction: CreateRestrictionInput): { valid: boolean; errors?: string[] };
+  formatActivityDetails?(activity: ActivityLog): Record<string, unknown>;
+  onRestrictionViolation?(profileId: string, reason: string): Promise<void>;
+  onDailyLimitReached?(profileId: string): Promise<void>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Store Interface
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface ParentalStore {
+  name: string;
+  initialize(): Promise<void>;
+
+  // Guardian settings
+  getSettings(userId: string): Promise<GuardianSettings | null>;
+  createSettings(input: CreateGuardianSettingsInput): Promise<GuardianSettings>;
+  updateSettings(userId: string, input: UpdateGuardianSettingsInput): Promise<GuardianSettings | null>;
+  setPin(userId: string, pinHash: string): Promise<void>;
+  verifyPin(userId: string, pinHash: string): Promise<boolean>;
+  incrementFailedPinAttempts(userId: string): Promise<number>;
+  resetFailedPinAttempts(userId: string): Promise<void>;
+
+  // Restrictions
+  getRestrictions(profileId: string): Promise<ProfileRestriction[]>;
+  createRestriction(input: CreateRestrictionInput): Promise<ProfileRestriction>;
+  updateRestriction(id: string, updates: Partial<ProfileRestriction>): Promise<ProfileRestriction | null>;
+  deleteRestriction(id: string): Promise<boolean>;
+  pauseProfile(profileId: string, until?: Date, reason?: string): Promise<void>;
+  resumeProfile(profileId: string): Promise<void>;
+
+  // Activity log
+  logActivity(input: LogActivityInput): Promise<ActivityLog>;
+  getActivityLog(userId: string, limit?: number, profileId?: string): Promise<ActivityLog[]>;
+
+  shutdown(): Promise<void>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Configuration Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface PostgresParentalStoreConfig {
+  pool: unknown | (() => unknown);
+  settingsTable?: string;
+  restrictionsTable?: string;
+  activityTable?: string;
+  schema?: string;
+  autoCreateTables?: boolean;
+}
+
+export interface ParentalApiConfig {
+  prefix?: string;
+  enabled?: boolean;
+}
+
+export interface ParentalPluginConfig {
+  store: ParentalStore;
+  adapter: ParentalAdapter;
+  maxPinAttempts?: number;
+  pinLockoutMinutes?: number;
+  api?: ParentalApiConfig;
+  debug?: boolean;
+}