@runhalo/engine 0.2.0 → 0.3.1

package/dist/scaffolds/templates/retention-policy.js

@@ -0,0 +1,247 @@
+"use strict";
+/**
+ * Data Retention Policy Scaffold
+ * Addresses: coppa-retention-005
+ * Generates data retention utility with cleanup script and deletion handler
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retentionPolicyTemplate = void 0;
+function generateReact(typescript) {
+    const ext = typescript ? 'ts' : 'js';
+    const typeAnnotations = typescript;
+    const utility = `/**
+ * Data Retention Policy — COPPA-compliant data lifecycle management
+ *
+ * COPPA requires:
+ * - Data collected from children must be deleted when no longer needed
+ * - Parents can request deletion of their child's data at any time
+ * - Deletion must be completed within a reasonable timeframe (48-hour SLA recommended)
+ * - Only collect data that is reasonably necessary
+ *
+ * This utility provides:
+ * - Schema helpers for marking records with retention metadata
+ * - A cleanup function for purging expired data
+ * - A deletion request handler for parent-initiated deletion
+ *
+ * Usage:
+ *   import { DataRetention, RETENTION_POLICIES } from './data-retention';
+ *
+ *   // Mark a record with retention metadata
+ *   const record = DataRetention.markForRetention(userData, 'user_profile');
+ *
+ *   // Check for expired records
+ *   const expired = DataRetention.isExpired(record);
+ *
+ *   // Handle parent deletion request
+ *   await DataRetention.handleDeletionRequest(userId);
+ *
+ * Generated by Halo (runhalo.dev) — COPPA compliance scaffold
+ */
+${typeAnnotations ? `
+export interface RetentionPolicy {
+  /** Category of data */
+  category: string;
+  /** Maximum retention period in days */
+  maxRetentionDays: number;
+  /** Whether this data type is required for service operation */
+  essential: boolean;
+  /** Description for privacy policy */
+  description: string;
+}
+
+export interface RetentionMetadata {
+  /** When the data was created */
+  createdAt: string;
+  /** When the data should be deleted */
+  expiresAt: string;
+  /** Retention policy category applied */
+  retentionCategory: string;
+  /** Whether a deletion request is pending */
+  deletionRequested?: boolean;
+  /** When deletion was requested */
+  deletionRequestedAt?: string;
+}
+
+export interface DeletionRequest {
+  userId: string;
+  requestedAt: string;
+  /** COPPA SLA: must be completed within this deadline */
+  deadline: string;
+  status: 'pending' | 'processing' | 'completed' | 'failed';
+  categories: string[];
+}
+` : ''}
+/**
+ * Default retention policies — customize per your data categories.
+ * COPPA best practice: shorter retention = lower risk.
+ */
+${typeAnnotations ? 'export const RETENTION_POLICIES: Record<string, RetentionPolicy> = {' : 'const RETENTION_POLICIES = {'}
+  /** User profile data — retained while account is active + 30 day grace period */
+  user_profile: {
+    category: 'user_profile',
+    maxRetentionDays: 365,
+    essential: true,
+    description: 'Basic account information needed for service operation',
+  },
+  /** Session data — short-lived, purged after 24 hours */
+  session: {
+    category: 'session',
+    maxRetentionDays: 1,
+    essential: true,
+    description: 'Temporary session data for authentication',
+  },
+  /** Analytics/telemetry — aggregated, purged after 90 days */
+  analytics: {
+    category: 'analytics',
+    maxRetentionDays: 90,
+    essential: false,
+    description: 'Anonymous usage analytics for product improvement',
+  },
+  /** User-generated content — retained while account is active */
+  user_content: {
+    category: 'user_content',
+    maxRetentionDays: 365,
+    essential: false,
+    description: 'Content created by the user within the service',
+  },
+  /** Support/communication — retained for 180 days */
+  support: {
+    category: 'support',
+    maxRetentionDays: 180,
+    essential: false,
+    description: 'Customer support interactions and communications',
+  },
+};
+
+/** COPPA-recommended maximum time to process a deletion request (48 hours) */
+const DELETION_SLA_HOURS = 48;
+
+${typeAnnotations ? 'export class DataRetention {' : 'class DataRetention {'}
+  /**
+   * Add retention metadata to a data record.
+   * Call this when creating or updating user data.
+   */
+  static markForRetention(
+    record${typeAnnotations ? ': Record<string, any>' : ''},
+    category${typeAnnotations ? ': string' : ''},
+    policyOverrides${typeAnnotations ? '?: Partial<RetentionPolicy>' : ''} = {}
+  )${typeAnnotations ? ': Record<string, any> & { _retention: RetentionMetadata }' : ''} {
+    const policy = { ...(RETENTION_POLICIES[category] || RETENTION_POLICIES.user_profile), ...policyOverrides };
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + policy.maxRetentionDays * 24 * 60 * 60 * 1000);
+
+    return {
+      ...record,
+      _retention: {
+        createdAt: now.toISOString(),
+        expiresAt: expiresAt.toISOString(),
+        retentionCategory: policy.category,
+      },
+    };
+  }
+
+  /**
+   * Check if a record has expired based on its retention metadata
+   */
+  static isExpired(record${typeAnnotations ? ': { _retention?: RetentionMetadata }' : ''})${typeAnnotations ? ': boolean' : ''} {
+    if (!record._retention?.expiresAt) return false;
+    return new Date() > new Date(record._retention.expiresAt);
+  }
+
+  /**
+   * Check if a deletion request is pending for a record
+   */
+  static isDeletionPending(record${typeAnnotations ? ': { _retention?: RetentionMetadata }' : ''})${typeAnnotations ? ': boolean' : ''} {
+    return record._retention?.deletionRequested === true;
+  }
+
+  /**
+   * Create a deletion request with COPPA SLA deadline.
+   *
+   * IMPORTANT: Implement the actual data deletion in your database layer.
+   * This function creates the request record — you must process it.
+   */
+  static createDeletionRequest(
+    userId${typeAnnotations ? ': string' : ''},
+    categories${typeAnnotations ? ': string[]' : ''} = Object.keys(RETENTION_POLICIES)
+  )${typeAnnotations ? ': DeletionRequest' : ''} {
+    const now = new Date();
+    const deadline = new Date(now.getTime() + DELETION_SLA_HOURS * 60 * 60 * 1000);
+
+    return {
+      userId,
+      requestedAt: now.toISOString(),
+      deadline: deadline.toISOString(), // 48-hour SLA
+      status: 'pending',
+      categories,
+    };
+  }
+
+  /**
+   * Get all retention policies (for privacy policy page generation)
+   */
+  static getPolicies()${typeAnnotations ? ': Record<string, RetentionPolicy>' : ''} {
+    return { ...RETENTION_POLICIES };
+  }
+
+  /**
+   * Filter an array of records, removing expired ones.
+   * Use this in a scheduled cleanup job.
+   *
+   * Example (cron job):
+   *   const records = await db.query('SELECT * FROM user_data');
+   *   const { active, expired } = DataRetention.partitionByExpiry(records);
+   *   await db.deleteMany(expired.map(r => r.id));
+   */
+  static partitionByExpiry(records${typeAnnotations ? ': Array<{ _retention?: RetentionMetadata }>' : ''})${typeAnnotations ? ': { active: any[]; expired: any[] }' : ''} {
+    const active${typeAnnotations ? ': any[]' : ''} = [];
+    const expired${typeAnnotations ? ': any[]' : ''} = [];
+
+    for (const record of records) {
+      if (DataRetention.isExpired(record) || DataRetention.isDeletionPending(record)) {
+        expired.push(record);
+      } else {
+        active.push(record);
+      }
+    }
+
+    return { active, expired };
+  }
+}
+
+${typeAnnotations ? '' : 'module.exports = { DataRetention, RETENTION_POLICIES, DELETION_SLA_HOURS };'}
+${typeAnnotations ? 'export { DELETION_SLA_HOURS };' : ''}
+`;
+    return [
+        {
+            relativePath: `utils/data-retention.${ext}`,
+            content: utility,
+            description: 'COPPA-compliant data retention utility with cleanup and deletion request handling',
+        },
+    ];
+}
+function generatePlainJS() {
+    // Reuse the same logic but without TypeScript annotations
+    const files = generateReact(false);
+    // Adjust path for plain JS (no utils/ nesting)
+    return files.map(f => ({
+        ...f,
+        relativePath: 'data-retention.js',
+    }));
+}
+exports.retentionPolicyTemplate = {
+    scaffoldId: 'retention-policy',
+    name: 'Data Retention Policy',
+    description: 'COPPA-compliant data retention lifecycle management with 48-hour deletion SLA',
+    ruleIds: ['coppa-retention-005'],
+    generate(framework, typescript) {
+        switch (framework) {
+            case 'react':
+            case 'nextjs':
+                return generateReact(typescript);
+            default:
+                return generatePlainJS();
+        }
+    },
+};
+//# sourceMappingURL=retention-policy.js.map

package/dist/scaffolds/templates/retention-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention-policy.js","sourceRoot":"","sources":["../../../src/scaffolds/templates/retention-policy.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runhalo/engine",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Halo rule engine — COPPA 2.0 risk detection via tree-sitter AST analysis",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",