@runhalo/engine 0.1.0

package/dist/index.js

@@ -0,0 +1,956 @@
+"use strict";
+/**
+ * Halo COPPA Rule Engine
+ * Core scanning logic for child safety compliance detection
+ *
+ * Sprint 2: Added rules 6-20 (coppa-sec-006 through coppa-default-020)
+ * Sprint 2: Added suppression system for // halo-ignore comments
+ * Sprint 1 Fixes: Added tree-sitter for AST analysis, YAML rule loading
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HaloEngine = exports.ETHICAL_RULES = exports.COPPA_RULES = exports.treeSitterParser = exports.TreeSitterParser = void 0;
+exports.loadRulesFromYAML = loadRulesFromYAML;
+exports.parseHaloignore = parseHaloignore;
+exports.shouldIgnoreFile = shouldIgnoreFile;
+exports.shouldIgnoreViolation = shouldIgnoreViolation;
+const fs = __importStar(require("fs"));
+const tree_sitter_1 = __importDefault(require("tree-sitter"));
+const tree_sitter_typescript_1 = __importDefault(require("tree-sitter-typescript"));
+const tree_sitter_javascript_1 = __importDefault(require("tree-sitter-javascript"));
+const yaml = __importStar(require("js-yaml"));
+// YAML Rule Loader - Load rules from coppa-tier-1.yaml
+function loadRulesFromYAML(yamlPath) {
+    try {
+        const yamlContent = fs.readFileSync(yamlPath, 'utf-8');
+        const config = yaml.load(yamlContent);
+        if (!config?.rules) {
+            console.warn(`No rules found in YAML file: ${yamlPath}`);
+            return [];
+        }
+        return config.rules.map((ruleConfig) => {
+            const metadata = ruleConfig.metadata || {};
+            const patterns = (ruleConfig.patterns || []).map((p) => {
+                return new RegExp(p.regex.pattern, p.regex.flags || 'g');
+            });
+            return {
+                id: metadata.id || '',
+                name: metadata.name || '',
+                severity: metadata.severity || 'medium',
+                description: metadata.coppaSection || '',
+                patterns,
+                fixSuggestion: ruleConfig.autoFix?.description || '',
+                penalty: metadata.penaltyRange || '',
+                languages: metadata.languages || []
+            };
+        });
+    }
+    catch (error) {
+        console.error(`Error loading YAML rules from ${yamlPath}:`, error);
+        return [];
+    }
+}
+// Tree-sitter Parser for AST analysis
+class TreeSitterParser {
+    constructor() {
+        this.parser = new tree_sitter_1.default();
+    }
+    /**
+     * Initialize parser with language
+     */
+    initialize(language) {
+        if (language === 'typescript') {
+            this.parser.setLanguage(tree_sitter_typescript_1.default.typescript);
+        }
+        else {
+            this.parser.setLanguage(tree_sitter_javascript_1.default);
+        }
+    }
+    /**
+     * Parse code and return AST
+     */
+    parse(code, language = 'typescript') {
+        this.initialize(language);
+        return this.parser.parse(code);
+    }
+    /**
+     * Find all function calls matching a name pattern
+     */
+    findFunctionCalls(code, functionName) {
+        const results = [];
+        const tree = this.parse(code);
+        const walk = (node) => {
+            // Check for call_expression nodes
+            if (node.type === 'call_expression') {
+                const funcNode = node.child(0);
+                if (funcNode && funcNode.text === functionName) {
+                    const startPosition = node.startPosition;
+                    results.push({
+                        line: startPosition.row + 1,
+                        column: startPosition.column + 1
+                    });
+                }
+            }
+            if (node.children) {
+                node.children.forEach(walk);
+            }
+        };
+        walk(tree.rootNode);
+        return results;
+    }
+    /**
+     * Extract all identifiers from code (for pattern matching)
+     */
+    extractIdentifiers(code) {
+        const identifiers = [];
+        const tree = this.parse(code);
+        const walk = (node) => {
+            if (node.type === 'identifier') {
+                identifiers.push(node.text);
+            }
+            if (node.children) {
+                node.children.forEach(walk);
+            }
+        };
+        walk(tree.rootNode);
+        return identifiers;
+    }
+}
+exports.TreeSitterParser = TreeSitterParser;
+// Default tree-sitter parser instance
+exports.treeSitterParser = new TreeSitterParser();
+// Parse suppression comments from content
+function parseSuppressions(content) {
+    const suppressions = new Map();
+    const lines = content.split('\n');
+    const pattern = /\/\/\s*halo-ignore(?::\s*([\w-]+(?:\s*,\s*[\w-]+)*))?/gi;
+    lines.forEach((line, index) => {
+        let match;
+        while ((match = pattern.exec(line)) !== null) {
+            const ruleIds = match[1] ? match[1].split(',').map((id) => id.trim()) : null;
+            suppressions.set(index + 1, ruleIds ? ruleIds.join(',') : 'all');
+        }
+    });
+    return suppressions;
+}
+// Check if a violation is suppressed
+function isViolationSuppressed(violation, suppressions, globalSuppressions) {
+    // Check same-line suppression (comment on same line as violation)
+    const sameLineSuppression = suppressions.get(violation.line);
+    if (sameLineSuppression) {
+        if (sameLineSuppression === 'all' || sameLineSuppression.includes(violation.ruleId)) {
+            return true;
+        }
+    }
+    // Check next-line suppression (comment on line above violation)
+    const prevLineSuppression = suppressions.get(violation.line - 1);
+    if (prevLineSuppression) {
+        if (prevLineSuppression === 'all' || prevLineSuppression.includes(violation.ruleId)) {
+            return true;
+        }
+    }
+    // Check global suppression (suppression before any code)
+    if (globalSuppressions.has(violation.line)) {
+        return true;
+    }
+    return false;
+}
+// COPPA Rule Definitions (Tier 1 - All 20 rules)
+// Rules 1-5 from Sprint 1, Rules 6-20 added in Sprint 2
+exports.COPPA_RULES = [
+    // ========== Rules 1-5 (Sprint 1) ==========
+    {
+        id: 'coppa-auth-001',
+        name: 'Unverified Social Login Providers',
+        severity: 'critical',
+        description: 'Social login (Google, Facebook, Twitter) without age gating is prohibited for child-directed apps',
+        patterns: [
+            /signInWithPopup\s*\(\s*\w+\s*,\s*['"](google|facebook|twitter|github)['"]/gi,
+            /signInWithPopup\s*\(\s*['"](google|facebook|twitter|github)['"]/gi,
+            /signInWithPopup\s*\(\s*\w+\s*,\s*\w+\s*\)/gi,
+            /firebase\.auth\(\)\s*\.\s*signInWithPopup/gi,
+            /passport\.authenticate\s*\(\s*['"](google|facebook|twitter)['"]/gi
+        ],
+        fixSuggestion: 'Wrap the auth call in a conditional check for user.age >= 13 or use signInWithParentEmail() for children',
+        penalty: '$51,744 per violation',
+        languages: ['typescript', 'javascript', 'python', 'swift']
+    },
+    {
+        id: 'coppa-data-002',
+        name: 'PII Collection in URL Parameters',
+        severity: 'high',
+        description: 'Email, name, DOB, or phone in GET request URLs exposes PII in logs',
+        patterns: [
+            /(\?|&)(email|first_?name|last_?name|dob|phone|birthdate)=/gi,
+            /axios\.get\s*\(\s*[`'"]https?:\/\/[^\s]*\?[^`'"]*\$\{/gi,
+            /fetch\s*\(\s*[`'"]https?:\/\/[^\s]*\?[^`'"]*\$\{/gi,
+            /\?[^'"`\s]*\$\{[^}]*(?:\.email|\.firstName|\.lastName|\.dob|\.phone)[^}]*\}/gi
+        ],
+        fixSuggestion: 'Switch to POST method and move PII to request body',
+        penalty: '$51,744 per violation',
+        languages: ['typescript', 'javascript', 'python', 'java', 'swift']
+    },
+    {
+        id: 'coppa-tracking-003',
+        name: 'Third-Party Ad Trackers',
+        severity: 'critical',
+        description: 'Facebook Pixel, Google Analytics, or other ad trackers without child_directed_treatment flag',
+        patterns: [
+            /fbq\s*\(\s*['"]init['"]/gi,
+            /ga\s*\(\s*['"]create['"]/gi,
+            /adsbygoogle/gi,
+            /gtag\s*\(\s*['"]config['"]/gi,
+            /google-analytics\.com\/analytics\.js/gi
+        ],
+        fixSuggestion: 'Add "child_directed_treatment": true or "restrictDataProcessing": true to SDK initialization',
+        penalty: '$51,744 per violation',
+        languages: ['typescript', 'javascript', 'html']
+    },
+    {
+        id: 'coppa-geo-004',
+        name: 'Precise Geolocation Collection',
+        severity: 'high',
+        description: 'High-accuracy geolocation without parental consent is prohibited',
+        patterns: [
+            /navigator\.geolocation\.getCurrentPosition/gi,
+            /navigator\.geolocation\.watchPosition/gi,
+            /CLLocationManager\.startUpdatingLocation\(\)/gi,
+            /locationServices\.requestLocation/gi
+        ],
+        fixSuggestion: 'Downgrade accuracy to kCLLocationAccuracyThreeKilometers or require parental consent',
+        penalty: '$51,744 per violation',
+        languages: ['typescript', 'javascript', 'swift', 'kotlin']
+    },
+    {
+        id: 'coppa-retention-005',
+        name: 'Missing Data Retention Policy',
+        severity: 'medium',
+        description: 'User schemas must have deleted_at, expiration_date, or TTL index for data retention',
+        patterns: [
+            /new\s+Schema\s*\(\s*\{[^{}]*\}/gi
+        ],
+        fixSuggestion: 'Add deleted_at column, expiration_date field, or TTL index to database schema',
+        penalty: 'Regulatory audit failure',
+        languages: ['typescript', 'javascript', 'python', 'sql', 'swift']
+    },
+    // ========== Rules 6-20 (Sprint 2) ==========
+    // Rule 6: Unencrypted PII Transmission
+    {
+        id: 'coppa-sec-006',
+        name: 'Unencrypted PII Transmission',
+        severity: 'critical',
+        description: 'HTTP transmission of PII exposes data in transit. All API endpoints handling personal information must use HTTPS.',
+        patterns: [
+            /http:\/\/[^\s]*(\/api\/|\/login|\/user|\/register|\/profile)/gi,
+            /http:\/\/localhost:[^\s]*(\/api\/)/gi,
+            /axios\.get\s*\(\s*['"]http:\/\//gi,
+            /fetch\s*\(\s*['"]http:\/\//gi,
+            /http:\/\/[^\s]*email[^\s]*/gi
+        ],
+        fixSuggestion: 'Replace http:// with https:// for all API endpoints and resources',
+        penalty: 'Security breach liability + COPPA penalties',
+        languages: ['typescript', 'javascript', 'python', 'java', 'swift']
+    },
+    // Rule 7: Passive Audio Recording
+    // Fixed Sprint 4: Skip audio:false, skip AudioContext (playback only), skip import-only
+    {
+        id: 'coppa-audio-007',
+        name: 'Unauthorized Audio Recording',
+        severity: 'high',
+        description: 'Audio recording without explicit user consent is prohibited. COPPA 2.0 clarifies voice prints as biometric data.',
+        patterns: [
+            /getUserMedia\s*\(\s*\{[^}]*audio\s*:\s*true[^}]*\}/gi,
+            /getUserMedia\s*\(\s*\{\s*audio\s*\}/gi,
+            /getUserMedia\s*\(\s*\{\s*audio\s*,/gi,
+            /AVAudioSession\s*\.\s*sharedInstance/gi,
+            /AVAudioRecorder\s*\(/gi,
+            /new\s+AudioRecord\s*\(/gi,
+            /new\s+MediaRecorder\s*\(/gi
+        ],
+        fixSuggestion: 'Wrap audio recording in click handler and add parental consent check',
+        penalty: '$51,744 per violation',
+        languages: ['typescript', 'javascript', 'swift', 'kotlin']
+    },
+    // Rule 8: Missing Privacy Policy Link
+    // Fixed Sprint 4: Only flag forms with registration-related fields (email, password, name, DOB)
+    // Fixed Phase B: Tightened regex — word boundary after "Form" prevents registerFormat/registerOption FPs
+    {
+        id: 'coppa-ui-008',
+        name: 'Missing Privacy Policy on Registration',
+        severity: 'medium',
+        description: 'Registration forms collecting PII must include a clear link to the privacy policy',
+        patterns: [
+            // PascalCase component names: SignUpForm, RegisterForm, RegistrationForm, CreateAccountForm
+            // \b after Form prevents matching registerFormat, registerFormats, etc.
+            /\b(?:SignUp|Register|Registration|CreateAccount)Form\b/gi,
+            // kebab-case / snake_case: sign-up-form, register_form, create-account-form
+            /\b(?:sign[-_]?up|register|registration|create[-_]?account)[-_]form\b/gi,
+            // HTML form elements with registration-related ids/classes
+            /<form[^>]*(?:id|class|name)\s*=\s*["'][^"']*(?:register|signup|sign[-_]up|create[-_]account)[^"']*["']/gi
+        ],
+        fixSuggestion: 'Add <a href="/privacy">Privacy Policy</a> link to registration form footer',
+        penalty: 'Compliance failure',
+        languages: ['typescript', 'javascript', 'html', 'tsx', 'jsx', 'php']
+    },
+    // Rule 9: Contact Info Collection Without Parent Email
+    {
+        id: 'coppa-flow-009',
+        name: 'Direct Contact Collection Without Parent Context',
+        severity: 'high',
+        description: 'Forms collecting child email/phone must also require parent email for consent verification',
+        patterns: [
+            /(child_email|student_email)\s*:\s*String/gi,
+            /(child_email|student_email|kid_email)\s*=/gi
+        ],
+        fixSuggestion: 'Make parent_email required when collecting child contact information',
+        penalty: '$51,744 per violation',
+        languages: ['typescript', 'javascript', 'python']
+    },
+    // Rule 10: Insecure Default Passwords
+    {
+        id: 'coppa-sec-010',
+        name: 'Weak Default Student Passwords',
+        severity: 'medium',
+        description: 'Default passwords like "password", "123456", or "changeme" create security vulnerabilities',
+        patterns: [
+            /(password|default_pass|temp_password)\s*=\s*['"](123456|password|changeme|student|welcome)['"]/gi,
+            /defaultPassword:\s*['"](123456|password|changeme)['"]/gi,
+            /initialPassword:\s*['"](123456|password)['"]/gi,
+            /pass\s*=\s*['"](student123|child123|default)['"]/gi
+        ],
+        fixSuggestion: 'Use a secure random string generator for temporary credentials',
+        penalty: 'Security audit failure',
+        languages: ['typescript', 'javascript', 'python', 'java', 'swift']
+    },
+    // Rule 11: Third-Party Chat Widgets
+    {
+        id: 'coppa-ext-011',
+        name: 'Unmoderated Third-Party Chat',
+        severity: 'high',
+        description: 'Third-party chat widgets (Intercom, Zendesk, Drift) allow children to disclose PII freely',
+        patterns: [
+            /intercom\.init/gi,
+            /zendesk\.init/gi,
+            /drift\.init/gi,
+            /<script[^>]+src=['"][^'"]*intercom/gi,
+            /<script[^>]+src=['"][^'"]*(zendesk|zdassets)/gi,
+            /Freshdesk|FreshChat/gi
+        ],
+        fixSuggestion: 'Disable chat widget for unauthenticated or under-13 users via conditional rendering',
+        penalty: '$51,744 per violation',
+        languages: ['typescript', 'javascript', 'html']
+    },
+    // Rule 12: Biometric Data Collection
+    {
+        id: 'coppa-bio-012',
+        name: 'Biometric Data Collection',
+        severity: 'critical',
+        description: 'Face recognition, voice prints, or gait analysis requires explicit parental consent. COPPA 2.0 explicitly classifies biometrics as PI.',
+        patterns: [
+            /(?:import\s+.*from\s+['"]face-api\.js['"]|require\s*\(\s*['"]face-api\.js['"]\s*\))/gi,
+            /LocalAuthentication.*evaluatePolicy/gi,
+            /FaceID|TouchID/gi,
+            /biometricAuth|BiometricAuth/g,
+            /voicePrint|VoicePrint/g,
+            /livenessCheck|LivenessCheck/g,
+            /FaceMatcher|FaceDetector|FaceRecognizer/g
+        ],
+        fixSuggestion: 'Ensure biometric data remains local-only (on-device) or obtain verifiable parental consent',
+        penalty: '$51,744 per violation',
+        languages: ['typescript', 'javascript', 'swift', 'kotlin']
+    },
+    // Rule 13: Push Notifications to Children
+    {
+        id: 'coppa-notif-013',
+        name: 'Direct Push Notifications Without Consent',
+        severity: 'medium',
+        description: 'Push notifications are "Online Contact Info" under COPPA 2.0. Direct notifications to children require parental consent.',
+        patterns: [
+            /FirebaseMessaging\.subscribeToTopic/gi,
+            /OneSignal\.promptForPushNotifications/gi,
+            /sendPushNotification\s*\(/gi,
+            /fcm\.send\s*\(/gi,
+            /PushManager\.subscribe\s*\(/gi,
+            /Notification\.requestPermission/gi,
+            /new\s+Notification\s*\(/gi
+        ],
+        fixSuggestion: 'Gate push notification subscription behind parental dashboard setting',
+        penalty: '$51,744 per violation',
+        languages: ['typescript', 'javascript', 'swift', 'kotlin']
+    },
+    // Rule 14: Unfiltered User Generated Content
+    {
+        id: 'coppa-ugc-014',
+        name: 'UGC Upload Without PII Filter',
+        severity: 'high',
+        description: 'Text areas for "bio", "about me", or comments must pass through PII scrubbing before database storage',
+        patterns: [
+            /<textarea[^>]*placeholder=["'](?:bio|about me|describe yourself)[^"']*["']/gi,
+            /user\.bio\s*=/gi,
+            /aboutMe\s*=/gi,
+            /(?:submit|save|post)Comment\s*\(/gi,
+            /saveBio\s*\(|updateBio\s*\(/gi,
+            /commentForm.*submit|handleCommentSubmit/gi
+        ],
+        fixSuggestion: 'Add middleware hook for PII scrubbing (regex or AWS Comprehend) before database storage',
+        penalty: '$51,744 per violation',
+        languages: ['typescript', 'javascript', 'python']
+    },
+    // Rule 15: XSS Vulnerabilities
+    // Fixed Sprint 4: Skip innerHTML='', localization, CSS injection, and self-clearing patterns
+    {
+        id: 'coppa-sec-015',
+        name: 'Reflected XSS Risk',
+        severity: 'medium',
+        description: 'DangerouslySetInnerHTML or innerHTML with user-controlled content creates XSS vulnerabilities',
+        patterns: [
+            /dangerouslySetInnerHTML\s*=\s*\{\s*\{\s*__html\s*:\s*(?!['"]<)[^}]*\}\s*\}/gi,
+            /\.innerHTML\s*=\s*\$\{/gi,
+            /\.innerHTML\s*=\s*(?!['"]?\s*['"]?\s*;)(?!.*[Ll]ocal(?:ize|ization))(?!.*styleContent)[^;]*\b(?:user|input|query|param|req\.|request\.|body\.|data\.)\w*/gi,
+            /\.html\s*\(\s*(?:user|req\.|request\.|params?\.)/gi,
+            /v-html\s*=\s*["']?(?!.*sanitize)/gi
+        ],
+        fixSuggestion: 'Use standard JSX rendering or DOMPurify before setting HTML content',
+        penalty: 'Security failure',
+        languages: ['typescript', 'javascript', 'tsx', 'jsx', 'vue']
+    },
+    // Rule 16: Missing Cookie Consent
+    // Fixed Sprint 4: Only flag tracking/PII cookies, not functional preferences (theme, view mode)
+    {
+        id: 'coppa-cookies-016',
+        name: 'Missing Cookie Notice',
+        severity: 'low',
+        description: 'Cookies or localStorage storing tracking data or PII requires a consent banner',
+        patterns: [
+            /document\.cookie\s*=\s*[^;]*(?:user|email|name|token|session|track|id|uid|analytics)/gi,
+            /localStorage\.setItem\s*\(\s*['"][^'"]*(?:user|email|token|session|track|auth|login|id|uid|analytics)[^'"]*['"]/gi,
+            /sessionStorage\.setItem\s*\(\s*['"][^'"]*(?:user|email|token|session|track|auth|login|id|uid|analytics)[^'"]*['"]/gi
+        ],
+        fixSuggestion: 'Add a cookie consent banner component before setting tracking or PII cookies',
+        penalty: 'Compliance warning',
+        languages: ['typescript', 'javascript']
+    },
+    // Rule 17: External Links to Non-Child-Safe Sites
+    // Fixed Sprint 4: Exclude privacy/TOS links, mailto, and common safe targets
+    {
+        id: 'coppa-ext-017',
+        name: 'Unwarned External Links',
+        severity: 'medium',
+        description: 'External links in child-facing views should trigger a "You are leaving..." modal',
+        patterns: [
+            /<a[^>]+href=["']https?:\/\/(?!.*(?:privacy|terms|legal|tos|policy|consent|support|help|docs|documentation))[^"']+["'][^>]*target=["']_blank["'][^>]*>/gi,
+            /window\.open\s*\(\s*['"]https?:\/\/(?!.*(?:privacy|terms|legal|tos|policy))/gi
+        ],
+        fixSuggestion: 'Wrap external links in SafeLink component with warning modal',
+        penalty: 'Warning',
+        languages: ['typescript', 'javascript', 'html', 'tsx', 'jsx']
+    },
+    // Rule 18: Analytics User ID Mapping
+    {
+        id: 'coppa-analytics-018',
+        name: 'Mapping PII to Analytics User IDs',
+        severity: 'high',
+        description: 'Passing email, name, or phone to analytics.identify() exposes PII to third parties',
+        patterns: [
+            /analytics\.identify\s*\([^)]*email/gi,
+            /mixpanel\.identify.*email/gi,
+            /segment\.identify.*email/gi,
+            /amplitude\.identify.*email/gi,
+            /identify\s*\(\s*\{[^}]*(?:email|name|phone)[^}]*\}/gi
+        ],
+        fixSuggestion: 'Hash user ID and omit email/name from analytics payload',
+        penalty: '$51,744 per violation',
+        languages: ['typescript', 'javascript']
+    },
+    // Rule 19: School Official Consent Bypass
+    // Fixed Sprint 4: Tightened patterns to match actual auth/registration flows only
+    {
+        id: 'coppa-edu-019',
+        name: 'Missing Teacher/School Verification',
+        severity: 'medium',
+        description: 'Teacher accounts using generic email (@gmail.com) bypass "School Official" consent exception',
+        patterns: [
+            /(?:teacher|educator)(?:Sign[Uu]p|[Rr]egist(?:er|ration))\s*(?:\(|=|:)/gi,
+            /createTeacherAccount|registerTeacher|teacherAuth/gi,
+            /role\s*(?:=|:)\s*['"]teacher['"].*(?:@gmail|@yahoo|@hotmail)/gi,
+            /isTeacher\s*&&\s*!.*\.edu/gi
+        ],
+        fixSuggestion: 'Restrict teacher sign-ups to verified EDU domains or require manual approval',
+        penalty: 'Loss of School Official consent status',
+        languages: ['typescript', 'javascript', 'python']
+    },
+    // Rule 20: Default Privacy Settings Public
+    {
+        id: 'coppa-default-020',
+        name: 'Default Public Profile Visibility',
+        severity: 'critical',
+        description: 'Default profile visibility must be private. COPPA 2.0 requires privacy by design.',
+        patterns: [
+            /isProfileVisible:\s*true/gi,
+            /visibility:\s*['"]public['"]/gi,
+            /defaultPrivacy:\s*['"]public['"]/gi,
+            /isPublic:\s*true[^}]*(profile|User)/gi,
+            /profileVisibility\s*=\s*['"]?(?:public|Public)['"]?/gi
+        ],
+        fixSuggestion: 'Change default visibility to "private" or false',
+        penalty: '$51,744 per violation',
+        languages: ['typescript', 'javascript', 'python', 'swift']
+    }
+];
+// Ethical Design Rules (Sprint 5 Preview)
+exports.ETHICAL_RULES = [
+    // ETHICAL-001: Infinite Scroll
+    {
+        id: 'ETHICAL-001',
+        name: 'Infinite Scroll / Endless Feed',
+        severity: 'high',
+        description: 'Infinite scroll exploits lack of impulse control. Children spend 2-3x longer on infinite feeds.',
+        patterns: [
+            /IntersectionObserver.*isIntersecting.*loadMore/gi,
+            /window\.addEventListener.*['"]scroll['"].*fetchNext/gi,
+            /import.*InfiniteScroll/gi,
+            /<InfiniteScroll/gi,
+            /ngx-infinite-scroll/gi,
+            /vue-infinite-loading/gi
+        ],
+        fixSuggestion: 'Replace infinite scroll with pagination or "Load More" buttons to create natural stopping points',
+        penalty: 'Ethical Design Violation',
+        languages: ['typescript', 'javascript', 'tsx', 'jsx', 'vue']
+    },
+    // ETHICAL-002: Streak Pressure
+    {
+        id: 'ETHICAL-002',
+        name: 'Streak Pressure Mechanics',
+        severity: 'high',
+        description: 'Streak mechanics use loss aversion to manufacture daily compulsive usage',
+        patterns: [
+            /streak.*>.*0.*loss/gi,
+            /lose.*your.*streak/gi,
+            /streak.*ends.*in/gi,
+            /don'?t.*break.*streak/gi,
+            /dailyStreak/gi,
+            /consecutiveDays/gi
+        ],
+        fixSuggestion: 'Remove streak loss penalties. Frame progress as cumulative (e.g., "15 days practiced") rather than consecutive.',
+        penalty: 'Ethical Design Violation',
+        languages: ['typescript', 'javascript', 'swift', 'kotlin']
+    },
+    // ETHICAL-003: Variable Rewards (Loot Boxes)
+    {
+        id: 'ETHICAL-003',
+        name: 'Variable Ratio Rewards (Loot Boxes)',
+        severity: 'critical',
+        description: 'Randomized rewards (loot boxes, gacha) exploit gambling psychology in developing brains',
+        patterns: [
+            /Math\.random\(\).*reward/gi,
+            /loot_?box/gi,
+            /gacha/gi,
+            /mystery_?crate/gi,
+            /openCrate/gi,
+            /rarityTable/gi,
+            /dropRates/gi
+        ],
+        fixSuggestion: 'Replace random rewards with transparent, effort-based rewards. Disclosure of odds is a minimum requirement.',
+        penalty: 'Ethical Design Violation',
+        languages: ['typescript', 'javascript', 'python', 'csharp']
+    },
+    // ETHICAL-004: Manipulative Notifications
+    {
+        id: 'ETHICAL-004',
+        name: 'Manipulative Notification Language',
+        severity: 'medium',
+        description: 'Notifications using urgency ("Hurry!", "Missing out") manipulate children\'s fear of social exclusion',
+        patterns: [
+            /hurry|limited\s*time|missing\s*out|don'?t\s*miss|left\s*behind/gi,
+            /everyone\s*else\s*is/gi,
+            /last\s*chance/gi,
+            /running\s*out/gi
+        ],
+        fixSuggestion: 'Use neutral, informational language. Avoid FOMO (Fear Of Missing Out) triggers.',
+        penalty: 'Ethical Design Violation',
+        languages: ['typescript', 'javascript', 'json', 'xml']
+    },
+    // ETHICAL-005: Artificial Scarcity
+    {
+        id: 'ETHICAL-005',
+        name: 'Artificial Scarcity / Countdowns',
+        severity: 'medium',
+        description: 'Fake scarcity ("Only 2 left!") and countdown timers pressure children into impulsive decisions',
+        patterns: [
+            /CountdownTimer/gi,
+            /only\s*\d+\s*left/gi,
+            /offer\s*ends\s*in/gi,
+            /selling\s*fast/gi,
+            /almost\s*sold\s*out/gi,
+            /limited\s*availability/gi
+        ],
+        fixSuggestion: 'Remove artificial urgency. If an offer expires, state the date calmly without countdown pressure.',
+        penalty: 'Ethical Design Violation',
+        languages: ['typescript', 'javascript', 'tsx', 'jsx', 'html']
+    }
+];
+/**
+ * Parse a .haloignore file content
+ *
+ * Format:
+ *   # comment
+ *   path/to/file.ts          — ignore entire file
+ *   **\/*.test.ts              — glob pattern to ignore files
+ *   rule:coppa-auth-001       — globally suppress a rule
+ *   src/auth.ts:coppa-auth-001 — suppress rule in specific file
+ */
+function parseHaloignore(content) {
+    const config = {
+        ignoredFiles: [],
+        globalRuleSuppressions: new Set(),
+        fileRuleSuppressions: new Map()
+    };
+    const lines = content.split('\n');
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        if (line.startsWith('rule:')) {
+            // Global rule suppression: rule:coppa-auth-001
+            const ruleId = line.slice(5).trim();
+            if (ruleId)
+                config.globalRuleSuppressions.add(ruleId);
+        }
+        else if (line.includes(':coppa-')) {
+            // Per-file rule suppression: src/auth.ts:coppa-auth-001
+            const colonIdx = line.indexOf(':coppa-');
+            const filePath = line.slice(0, colonIdx).trim();
+            const ruleId = line.slice(colonIdx + 1).trim();
+            if (filePath && ruleId) {
+                if (!config.fileRuleSuppressions.has(filePath)) {
+                    config.fileRuleSuppressions.set(filePath, new Set());
+                }
+                config.fileRuleSuppressions.get(filePath).add(ruleId);
+            }
+        }
+        else {
+            // File glob pattern
+            config.ignoredFiles.push(line);
+        }
+    }
+    return config;
+}
+/**
+ * Check if a file should be ignored based on .haloignore config
+ */
+function shouldIgnoreFile(filePath, config) {
+    const normalized = filePath.replace(/\\/g, '/');
+    for (const pattern of config.ignoredFiles) {
+        if (minimatch(normalized, pattern))
+            return true;
+    }
+    return false;
+}
+/**
+ * Check if a violation should be ignored based on .haloignore config
+ */
+function shouldIgnoreViolation(violation, config) {
+    // Global rule suppression
+    if (config.globalRuleSuppressions.has(violation.ruleId))
+        return true;
+    // Per-file rule suppression
+    const normalized = violation.filePath.replace(/\\/g, '/');
+    const fileSuppressions = config.fileRuleSuppressions.get(normalized);
+    if (fileSuppressions?.has(violation.ruleId))
+        return true;
+    return false;
+}
+/**
+ * Simple glob matching (supports * and **)
+ */
+function minimatch(filePath, pattern) {
+    // Convert glob to regex
+    const regexStr = pattern
+        .replace(/\./g, '\\.')
+        .replace(/\*\*/g, '{{GLOBSTAR}}')
+        .replace(/\*/g, '[^/]*')
+        .replace(/\{\{GLOBSTAR\}\}/g, '.*');
+    const regex = new RegExp(`^${regexStr}$`);
+    return regex.test(filePath);
+}
+// Engine class
+class HaloEngine {
+    constructor(config = {}) {
+        this.config = config;
+        this.treeSitter = new TreeSitterParser();
+        // Load rules - first try YAML if path provided, otherwise use hardcoded rules
+        let loadedRules = [];
+        if (config.rulesPath) {
+            // Load from YAML file
+            loadedRules = loadRulesFromYAML(config.rulesPath);
+        }
+        // If no YAML rules loaded, fall back to hardcoded COPPA_RULES
+        this.rules = loadedRules.length > 0
+            ? loadedRules
+            : (config.rules
+                ? exports.COPPA_RULES.filter(r => config.rules.includes(r.id))
+                : exports.COPPA_RULES);
+        // Add Ethical Design Rules if enabled (Sprint 5 Preview)
+        if (config.ethical) {
+            this.rules = [...this.rules, ...exports.ETHICAL_RULES];
+        }
+        if (config.severityFilter) {
+            this.rules = this.rules.filter(r => config.severityFilter.includes(r.severity));
+        }
+    }
+    /**
+     * Get the tree-sitter parser for advanced AST analysis
+     */
+    getParser() {
+        return this.treeSitter;
+    }
+    /**
+     * Scan using tree-sitter AST analysis (advanced mode)
+     */
+    scanFileWithAST(filePath, content, language = 'typescript') {
+        // First get regex-based violations
+        const violations = this.scanFile(filePath, content);
+        // Then enhance with AST analysis
+        try {
+            const identifiers = this.treeSitter.extractIdentifiers(content);
+            const functionCalls = this.treeSitter.findFunctionCalls(content, 'signInWithPopup');
+            // Add AST-based detection for social login
+            for (const call of functionCalls) {
+                // Check if already detected by regex
+                const exists = violations.some(v => v.ruleId === 'coppa-auth-001' &&
+                    v.line === call.line);
+                if (!exists) {
+                    const authRule = exports.COPPA_RULES.find(r => r.id === 'coppa-auth-001');
+                    if (authRule) {
+                        violations.push({
+                            ruleId: 'coppa-auth-001',
+                            ruleName: authRule.name,
+                            severity: authRule.severity,
+                            filePath,
+                            line: call.line,
+                            column: call.column,
+                            message: `${authRule.name}: Detected via AST analysis`,
+                            codeSnippet: content.split('\n')[call.line - 1]?.trim() || '',
+                            fixSuggestion: authRule.fixSuggestion,
+                            penalty: authRule.penalty
+                        });
+                    }
+                }
+            }
+        }
+        catch (error) {
+            // If AST parsing fails, fall back to regex-only
+            console.warn('AST parsing failed, using regex-only mode:', error);
+        }
+        return violations;
+    }
+    /**
+     * Get the ignore config (if any)
+     */
+    getIgnoreConfig() {
+        return this.config.ignoreConfig;
+    }
+    /**
+     * Scan a single file for violations
+     */
+    scanFile(filePath, content) {
+        // Check .haloignore — skip entire file if matched
+        const ignoreConfig = this.config.ignoreConfig;
+        if (ignoreConfig && shouldIgnoreFile(filePath, ignoreConfig)) {
+            return [];
+        }
+        const violations = [];
+        const lines = content.split('\n');
+        // Parse suppression comments
+        const suppressions = parseSuppressions(content);
+        // Track lines with global suppressions (at top of file)
+        const globalSuppressionLines = new Set();
+        for (const [line, rules] of suppressions.entries()) {
+            if (rules === 'all') {
+                globalSuppressionLines.add(line);
+            }
+        }
+        for (const rule of this.rules) {
+            // Special handling for coppa-retention-005: skip if schema has retention fields
+            if (rule.id === 'coppa-retention-005') {
+                // Check if the content has retention-related fields
+                const hasRetention = /deletedAt|deleted_at|expires|TTL|retention|paranoid|expiration/i.test(content);
+                if (!hasRetention) {
+                    // Continue with normal pattern matching
+                }
+                else {
+                    // Has retention fields - still scan but be more careful
+                    // Only flag schemas that clearly lack retention
+                    const schemaMatches = content.match(/new\s+Schema\s*\(\s*\{[^{}]*\}/gi);
+                    if (schemaMatches) {
+                        for (const schemaMatch of schemaMatches) {
+                            // Check if this specific schema has retention
+                            const surroundingContext = content.substring(Math.max(0, content.indexOf(schemaMatch) - 50), Math.min(content.length, content.indexOf(schemaMatch) + schemaMatch.length + 200));
+                            if (/deletedAt|deleted_at|expires|TTL|paranoid/i.test(surroundingContext)) {
+                                continue; // Skip this match - has retention
+                            }
+                            // This schema lacks retention - fall through to normal pattern matching
+                        }
+                    }
+                }
+            }
+            for (const pattern of rule.patterns) {
+                // Reset regex state
+                pattern.lastIndex = 0;
+                // Find all matches in content
+                let match;
+                while ((match = pattern.exec(content)) !== null) {
+                    // Calculate line and column from match position
+                    const beforeMatch = content.substring(0, match.index);
+                    const lineNumber = (beforeMatch.match(/\n/g) || []).length + 1;
+                    // Get the line content for snippet
+                    const lineIndex = lineNumber - 1;
+                    const lineContent = lines[lineIndex] || '';
+                    // Calculate column
+                    const lastNewline = beforeMatch.lastIndexOf('\n');
+                    const column = match.index - lastNewline;
+                    // Skip if the line is a comment (// or /* or * or <!-- or #)
+                    const trimmedLine = lineContent.trim();
+                    if (trimmedLine.startsWith('//') || trimmedLine.startsWith('/*') || trimmedLine.startsWith('*') || trimmedLine.startsWith('<!--') || trimmedLine.startsWith('#')) {
+                        // Exception: don't skip halo-ignore comments (those are suppression directives)
+                        if (!trimmedLine.includes('halo-ignore')) {
+                            continue;
+                        }
+                    }
+                    // For coppa-ext-017: skip matches that are own-domain links
+                    // Check both match[0] (captures multi-line <a> tags) and lineContent (captures window.open)
+                    if (rule.id === 'coppa-ext-017' && this.config.projectDomains?.length) {
+                        const checkText = (match[0] + ' ' + lineContent).toLowerCase();
+                        const isOwnDomain = this.config.projectDomains.some(domain => checkText.includes(domain.toLowerCase()));
+                        if (isOwnDomain)
+                            continue;
+                    }
+                    // Check if this violation already exists (avoid duplicates)
+                    const exists = violations.some(v => v.ruleId === rule.id &&
+                        v.line === lineNumber &&
+                        v.filePath === filePath);
+                    if (!exists) {
+                        // Check suppression
+                        const suppressed = this.config.suppressions?.enabled !== false &&
+                            isViolationSuppressed({ ruleId: rule.id, line: lineNumber, ruleName: '', severity: 'low', filePath: '', column: 0, message: '', codeSnippet: '', fixSuggestion: '' }, suppressions, globalSuppressionLines);
+                        // Get suppression comment if suppressed
+                        let suppressionComment;
+                        if (suppressed) {
+                            suppressionComment = suppressions.get(lineNumber);
+                        }
+                        violations.push({
+                            ruleId: rule.id,
+                            ruleName: rule.name,
+                            severity: rule.severity,
+                            filePath,
+                            line: lineNumber,
+                            column: column + 1,
+                            message: `${rule.name}: ${rule.description}`,
+                            codeSnippet: lineContent.trim().substring(0, 100).replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, ''),
+                            fixSuggestion: rule.fixSuggestion,
+                            penalty: rule.penalty,
+                            suppressed: suppressed || false,
+                            suppressionComment
+                        });
+                    }
+                }
+            }
+        }
+        // Filter suppressed if configured
+        if (this.config.suppressions?.enabled !== false && !this.config.includeSuppressed) {
+            const unsuppressed = violations.filter(v => !v.suppressed);
+            // Apply .haloignore per-violation filtering
+            if (ignoreConfig) {
+                return unsuppressed.filter(v => !shouldIgnoreViolation(v, ignoreConfig));
+            }
+            return unsuppressed;
+        }
+        // Even when showing suppressed, still apply .haloignore
+        if (ignoreConfig) {
+            return violations.filter(v => !shouldIgnoreViolation(v, ignoreConfig));
+        }
+        return violations;
+    }
+    /**
+     * Get all rules
+     */
+    getRules() {
+        return this.rules;
+    }
+    /**
+     * Get rule by ID
+     */
+    getRule(ruleId) {
+        return exports.COPPA_RULES.find(r => r.id === ruleId);
+    }
+    /**
+     * Explain a rule (for MCP)
+     */
+    explainRule(ruleId) {
+        const rule = this.getRule(ruleId);
+        if (!rule) {
+            return `Rule ${ruleId} not found.`;
+        }
+        return `
+Rule: ${rule.id}
+Name: ${rule.name}
+Severity: ${rule.severity.toUpperCase()}
+
+Description: ${rule.description}
+
+COPPA Reference: ${rule.penalty}
+
+Fix Suggestion: ${rule.fixSuggestion}
+
+Supported Languages: ${rule.languages.join(', ')}
+    `.trim();
+    }
+    /**
+     * Get fix suggestion for a rule (for MCP)
+     */
+    getFixSuggestion(ruleId) {
+        const rule = this.getRule(ruleId);
+        if (!rule) {
+            return `Rule ${ruleId} not found.`;
+        }
+        return rule.fixSuggestion;
+    }
+}
+exports.HaloEngine = HaloEngine;
+exports.default = HaloEngine;
+//# sourceMappingURL=index.js.map