@etalon/core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,557 @@
+interface Vendor {
+    id: string;
+    domains: string[];
+    name: string;
+    company: string;
+    category: VendorCategory;
+    gdpr_compliant: boolean;
+    dpa_url?: string;
+    privacy_policy?: string;
+    purpose: string;
+    data_collected: string[];
+    retention_period?: string;
+    last_verified?: string;
+    risk_score: number;
+    alternatives?: string[];
+}
+type VendorCategory = 'analytics' | 'advertising' | 'social' | 'cdn' | 'payments' | 'chat' | 'heatmaps' | 'ab_testing' | 'error_tracking' | 'tag_manager' | 'consent' | 'video' | 'fonts' | 'security' | 'push' | 'forms' | 'referral' | 'booking' | 'maps' | 'web3' | 'b2b_intelligence' | 'other';
+interface Category {
+    id: VendorCategory;
+    name: string;
+    description: string;
+    risk_level: 'low' | 'medium' | 'high' | 'critical';
+}
+interface VendorDatabase {
+    version: string;
+    last_updated: string;
+    vendors: Vendor[];
+    categories: Category[];
+}
+interface ScanRequest {
+    url: string;
+    deep?: boolean;
+    timeout?: number;
+    waitForNetworkIdle?: boolean;
+    userAgent?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+interface NetworkRequest {
+    url: string;
+    domain: string;
+    method: string;
+    type: string;
+    timestamp: string;
+    statusCode?: number;
+    contentType?: string;
+    size?: number;
+}
+interface DetectedVendor {
+    vendor: Vendor;
+    requests: NetworkRequest[];
+}
+interface UnknownDomain {
+    domain: string;
+    requests: NetworkRequest[];
+    suggestedAction: 'submit_for_review' | 'likely_benign' | 'investigate';
+}
+type RiskLevel = 'low' | 'medium' | 'high' | 'critical';
+interface ScanSummary {
+    totalRequests: number;
+    thirdPartyRequests: number;
+    knownVendors: number;
+    unknownDomains: number;
+    highRisk: number;
+    mediumRisk: number;
+    lowRisk: number;
+}
+interface ScanReport {
+    meta: {
+        etalonVersion: string;
+        scanDate: string;
+        scanDurationMs: number;
+        url: string;
+        deep: boolean;
+    };
+    summary: ScanSummary;
+    vendors: DetectedVendor[];
+    unknown: UnknownDomain[];
+    recommendations: Recommendation[];
+}
+interface Recommendation {
+    type: 'high_risk_vendor' | 'missing_dpa' | 'unknown_tracker' | 'consider_alternative';
+    vendorId?: string;
+    domain?: string;
+    message: string;
+}
+interface OpticConfig {
+    version: string;
+    sites?: SiteConfig[];
+    allowlist?: AllowlistEntry[];
+    notifications?: NotificationConfig;
+    scan?: ScanConfig;
+}
+interface SiteConfig {
+    url: string;
+    name: string;
+    schedule?: 'daily' | 'weekly' | 'on-commit';
+}
+interface AllowlistEntry {
+    vendor_id?: string;
+    domain?: string;
+    reason: string;
+    approved_by?: string;
+    approved_date?: string;
+    notes?: string;
+}
+interface NotificationConfig {
+    email?: string;
+    slack_webhook?: string;
+    threshold?: 'low' | 'medium' | 'high';
+}
+interface ScanConfig {
+    wait_for_network_idle?: boolean;
+    timeout?: number;
+    user_agent?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+
+/**
+ * VendorRegistry provides O(1) domain-to-vendor lookups, category filtering,
+ * and search capabilities over the ETALON vendor database.
+ */
+declare class VendorRegistry {
+    private vendors;
+    private categories;
+    private domainMap;
+    private version;
+    private lastUpdated;
+    /**
+     * Load the vendor database from a JSON file.
+     * If no path is provided, loads the bundled vendors.json.
+     */
+    static load(path?: string): VendorRegistry;
+    /**
+     * Load from an in-memory VendorDatabase object (useful for testing).
+     */
+    static fromDatabase(db: VendorDatabase): VendorRegistry;
+    /**
+     * Look up a vendor by domain.
+     * Tries exact match first, then walks up parent domains.
+     *
+     * @param domainOrUrl - A domain (e.g. "ssl.google-analytics.com") or full URL
+     * @returns The matched Vendor, or null if not found
+     */
+    lookupDomain(domainOrUrl: string): Vendor | null;
+    /**
+     * Get all vendors in a specific category.
+     */
+    getByCategory(category: VendorCategory): Vendor[];
+    /**
+     * Get all GDPR-compliant vendors.
+     */
+    getCompliant(): Vendor[];
+    /**
+     * Get all available categories.
+     */
+    getCategories(): Category[];
+    /**
+     * Search vendors by name or company (case-insensitive substring match).
+     */
+    search(query: string): Vendor[];
+    /**
+     * Get all vendors.
+     */
+    getAllVendors(): Vendor[];
+    /**
+     * Get a vendor by its ID.
+     */
+    getById(id: string): Vendor | null;
+    /**
+     * Get registry metadata.
+     */
+    getMetadata(): {
+        version: string;
+        lastUpdated: string;
+        vendorCount: number;
+        categoryCount: number;
+        domainCount: number;
+    };
+    /**
+     * Default path to the bundled vendors.json file.
+     */
+    private static defaultPath;
+}
+
+/**
+ * Domain utility functions for URL parsing and domain matching.
+ */
+/**
+ * Extract the hostname (domain) from a URL string.
+ * Returns null for invalid URLs, data URIs, etc.
+ */
+declare function extractDomain(url: string): string | null;
+/**
+ * Get all parent domains of a given hostname.
+ * e.g., "ssl.google-analytics.com" → ["google-analytics.com", "com"]
+ *
+ * Stops at TLD level (single-label domains are excluded from results).
+ */
+declare function getParentDomains(domain: string): string[];
+/**
+ * Check if a request domain is first-party relative to the scanned site.
+ * First-party means the domain is the same or a subdomain of the site domain.
+ */
+declare function isFirstParty(requestDomain: string, siteDomain: string): boolean;
+/**
+ * Normalize a URL for consistent processing.
+ * Adds https:// if no protocol is specified.
+ */
+declare function normalizeUrl(url: string): string;
+
+type FindingSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+type FindingCategory = 'code' | 'schema' | 'config';
+interface AuditFinding {
+    id: string;
+    category: FindingCategory;
+    severity: FindingSeverity;
+    title: string;
+    message: string;
+    file: string;
+    line?: number;
+    column?: number;
+    vendorId?: string;
+    rule: string;
+    fix?: string;
+    blame?: BlameInfo;
+    gdprArticles?: GdprReference$1[];
+}
+interface BlameInfo {
+    author: string;
+    email: string;
+    date: string;
+    commit: string;
+    commitMessage: string;
+}
+interface DiffResult {
+    added: AuditFinding[];
+    removed: AuditFinding[];
+    unchanged: AuditFinding[];
+}
+interface GdprReference$1 {
+    article: string;
+    title: string;
+    url: string;
+}
+type ComplianceGrade = 'A' | 'B' | 'C' | 'D' | 'F';
+interface ComplianceScore {
+    score: number;
+    grade: ComplianceGrade;
+    breakdown: {
+        critical: number;
+        high: number;
+        medium: number;
+        low: number;
+        info: number;
+    };
+}
+interface AuditReport {
+    meta: {
+        etalonVersion: string;
+        auditDate: string;
+        auditDurationMs: number;
+        directory: string;
+        stack: StackInfo;
+    };
+    summary: AuditSummary;
+    score?: ComplianceScore;
+    findings: AuditFinding[];
+    recommendations: string[];
+}
+interface AuditSummary {
+    totalFindings: number;
+    critical: number;
+    high: number;
+    medium: number;
+    low: number;
+    info: number;
+    trackerSdksFound: number;
+    piiColumnsFound: number;
+    configIssues: number;
+}
+type Language = 'javascript' | 'typescript' | 'python' | 'rust' | 'unknown';
+type Framework = 'nextjs' | 'express' | 'fastify' | 'nuxt' | 'svelte' | 'django' | 'flask' | 'fastapi' | 'actix' | 'axum' | 'rocket' | 'none';
+type ORM = 'prisma' | 'typeorm' | 'drizzle' | 'sequelize' | 'django-orm' | 'sqlalchemy' | 'diesel' | 'sea-orm' | 'raw-sql' | 'none';
+interface StackInfo {
+    languages: Language[];
+    framework: Framework;
+    orm: ORM;
+    packageManager: 'npm' | 'yarn' | 'pnpm' | 'pip' | 'poetry' | 'cargo' | 'unknown';
+    detectedFiles: string[];
+}
+interface TrackerPattern {
+    vendorId: string;
+    severity: FindingSeverity;
+}
+interface TrackerPatternDatabase {
+    npm: Record<string, TrackerPattern>;
+    pypi: Record<string, TrackerPattern>;
+    cargo: Record<string, TrackerPattern>;
+    envVars: Record<string, TrackerPattern>;
+    htmlPatterns: Array<{
+        pattern: string;
+        vendorId: string;
+        severity: FindingSeverity;
+    }>;
+    importPatterns: Array<{
+        pattern: string;
+        language: Language;
+        vendorId: string;
+        severity: FindingSeverity;
+    }>;
+}
+
+/**
+ * Auto-detect the project stack from filesystem presence.
+ */
+declare function detectStack(directory: string): StackInfo;
+
+/**
+ * Scan source files for tracker SDK usage, hardcoded tracking pixels,
+ * tracker-related env vars, and raw cookie writes.
+ */
+declare function scanCode(files: string[], baseDir: string, stack: StackInfo, patterns: TrackerPatternDatabase): AuditFinding[];
+
+/**
+ * Scan database schema files for PII storage patterns.
+ */
+declare function scanSchemas(files: string[], baseDir: string, stack: StackInfo): AuditFinding[];
+
+/**
+ * Scan configuration files for privacy/security issues.
+ */
+declare function scanConfigs(files: string[], baseDir: string, stack: StackInfo): AuditFinding[];
+
+/**
+ * Scan source files for server-side API calls to tracking service endpoints.
+ * These requests bypass client-side privacy controls (ad blockers, consent banners).
+ */
+declare function scanServerTracking(files: string[], baseDir: string, _stack: StackInfo): AuditFinding[];
+
+/**
+ * Scan for CNAME cloaking patterns across DNS configs, IaC, proxy configs,
+ * and framework-level rewrites/proxies.
+ */
+declare function scanCnameCloaking(files: string[], baseDir: string, stack: StackInfo): AuditFinding[];
+
+/**
+ * Format an AuditReport as SARIF 2.1.0.
+ * Compatible with GitHub Code Scanning and other SARIF consumers.
+ * Spec: https://sarifweb.azurewebsites.net/
+ */
+declare function formatAuditSarif(report: AuditReport): string;
+
+/**
+ * Compare two audit reports to identify added, removed, and unchanged findings.
+ * Used by the GitHub Action to surface only new issues introduced in a PR.
+ */
+declare function diffReports(current: AuditReport, baseline: AuditReport): DiffResult;
+/**
+ * Check whether diff results should block a PR based on minimum severity threshold.
+ */
+declare function shouldBlock(diff: DiffResult, threshold: FindingSeverity): boolean;
+
+/**
+ * Check if we're inside a git repository.
+ */
+declare function isGitRepo(cwd?: string): boolean;
+/**
+ * Get blame info for a specific line in a file.
+ */
+declare function getBlameForLine(filePath: string, lineNumber: number, cwd?: string): BlameInfo | null;
+/**
+ * Enrich audit findings with git blame information.
+ * Only enriches findings that have a file and line number.
+ */
+declare function enrichFindings(findings: AuditFinding[], cwd?: string): AuditFinding[];
+/**
+ * Group findings by author for reporting.
+ */
+declare function groupByAuthor(findings: AuditFinding[]): Map<string, AuditFinding[]>;
+
+interface GdprReference {
+    article: string;
+    title: string;
+    url: string;
+}
+declare const GDPR_RULE_MAP: Record<string, GdprReference[]>;
+/**
+ * Enrich findings with GDPR article references.
+ */
+declare function enrichWithGdpr(findings: AuditFinding[]): AuditFinding[];
+
+/**
+ * Calculate a compliance score (0–100) from an audit report.
+ *
+ * Formula: score = max(0, 100 - Σ(severity_weight × count))
+ *
+ * Grade scale:
+ *   A = 90–100 (excellent)
+ *   B = 75–89  (good, minor issues)
+ *   C = 60–74  (fair, needs attention)
+ *   D = 40–59  (poor, significant issues)
+ *   F = 0–39   (failing, critical issues)
+ */
+declare function calculateScore(report: AuditReport): ComplianceScore;
+/**
+ * Get styling hints for a grade (for badges, HTML reports, etc.).
+ */
+declare function gradeColor(grade: ComplianceGrade): string;
+
+/**
+ * Generate a shields.io-style SVG badge for the compliance grade.
+ */
+declare function generateBadgeSvg(score: ComplianceScore): string;
+/**
+ * Generate a shields.io badge URL for an ETALON score.
+ * Uses the shields.io endpoint badge format with the ETALON API.
+ */
+declare function badgeUrl(grade: string, score: number): string;
+/**
+ * Generate markdown for embedding a badge.
+ */
+declare function badgeMarkdown(grade: string, score: number): string;
+
+interface FilePatch {
+    file: string;
+    line: number;
+    rule: string;
+    oldContent: string;
+    newContent: string;
+    description: string;
+}
+/**
+ * Generate patches for fixable findings.
+ */
+declare function generatePatches(findings: AuditFinding[], baseDir: string): FilePatch[];
+/**
+ * Apply patches to files.
+ */
+declare function applyPatches(patches: FilePatch[], baseDir: string): number;
+/**
+ * List of rules that have auto-fixers.
+ */
+declare function fixableRules(): string[];
+
+interface CustomRule {
+    name: string;
+    description: string;
+    severity: FindingSeverity;
+    patterns: CustomPattern[];
+    gdpr_articles?: string[];
+    fix?: string;
+}
+interface CustomPattern {
+    regex: string;
+    languages?: string[];
+    message: string;
+}
+/**
+ * Load custom rules from a directory of YAML files.
+ * Expected location: .etalon/rules/*.yaml
+ */
+declare function loadCustomRules(directory: string): CustomRule[];
+/**
+ * Scan files using custom rules and return findings.
+ */
+declare function scanWithCustomRules(files: string[], directory: string, rules: CustomRule[]): AuditFinding[];
+
+type FlowNodeType = 'source' | 'storage' | 'sink';
+interface FlowNode {
+    type: FlowNodeType;
+    label: string;
+    file: string;
+    line: number;
+    piiType: string;
+    detail: string;
+}
+interface FlowEdge {
+    from: number;
+    to: number;
+    label?: string;
+}
+interface DataFlowMap {
+    nodes: FlowNode[];
+    edges: FlowEdge[];
+}
+/**
+ * Analyze data flow across files — find sources, storage, and sinks of PII.
+ */
+declare function analyzeDataFlow(files: string[], directory: string): DataFlowMap;
+/**
+ * Generate a Mermaid diagram from the data flow map.
+ */
+declare function toMermaid(flow: DataFlowMap): string;
+/**
+ * Generate a text summary of the data flow.
+ */
+declare function toTextSummary(flow: DataFlowMap): string;
+
+interface PolicyInput {
+    siteUrl?: string;
+    projectDir?: string;
+    companyName: string;
+    companyEmail: string;
+    companyCountry?: string;
+}
+interface PolicySection {
+    id: string;
+    title: string;
+    content: string;
+}
+interface PolicyVendorEntry {
+    vendorId: string;
+    vendorName: string;
+    company: string;
+    category: string;
+    purpose: string;
+    dataCollected: string[];
+    privacyPolicyUrl?: string;
+    dpaUrl?: string;
+    retentionPeriod?: string;
+    gdprCompliant: boolean;
+    source: 'code' | 'network' | 'both';
+}
+interface GeneratedPolicy {
+    sections: PolicySection[];
+    vendors: PolicyVendorEntry[];
+    piiTypes: string[];
+    fullText: string;
+    meta: {
+        generatedAt: string;
+        etalonVersion: string;
+        sources: string[];
+    };
+}
+interface PolicyGeneratorInput {
+    input: PolicyInput;
+    audit?: AuditReport;
+    networkVendorIds?: Set<string>;
+    dataFlow?: DataFlowMap;
+}
+declare function generatePolicy(opts: PolicyGeneratorInput): GeneratedPolicy;
+
+/**
+ * Run a full audit on a project directory.
+ */
+declare function auditProject(directory: string, options?: {
+    severity?: string;
+    includeBlame?: boolean;
+}): Promise<AuditReport>;
+
+export { type AllowlistEntry, type AuditFinding, type AuditReport, type AuditSummary, type BlameInfo, type Category, type ComplianceGrade, type ComplianceScore, type CustomPattern, type CustomRule, type DataFlowMap, type DetectedVendor, type DiffResult, type FilePatch, type FindingCategory, type FindingSeverity, type FlowEdge, type FlowNode, type FlowNodeType, GDPR_RULE_MAP, type GdprReference$1 as GdprReference, type GeneratedPolicy, type NetworkRequest, type NotificationConfig, type OpticConfig, type PolicyGeneratorInput, type PolicyInput, type PolicySection, type PolicyVendorEntry, type Recommendation, type RiskLevel, type ScanConfig, type ScanReport, type ScanRequest, type ScanSummary, type SiteConfig, type StackInfo, type UnknownDomain, type Vendor, type VendorCategory, type VendorDatabase, VendorRegistry, analyzeDataFlow, applyPatches, auditProject, badgeMarkdown, badgeUrl, calculateScore, detectStack, diffReports, enrichFindings, enrichWithGdpr, extractDomain, fixableRules, formatAuditSarif, generateBadgeSvg, generatePatches, generatePolicy, getBlameForLine, getParentDomains, gradeColor, groupByAuthor, isFirstParty, isGitRepo, loadCustomRules, normalizeUrl, scanCnameCloaking, scanCode, scanConfigs, scanSchemas, scanServerTracking, scanWithCustomRules, shouldBlock, toMermaid, toTextSummary };