har-o-scope 0.1.0

package/dist/lib/trace-sanitizer.js

@@ -0,0 +1,85 @@
+/**
+ * Trace sanitizer: sanitizes output for verbose/trace/error messages.
+ * Public exports used by CLI --verbose, browser RuleTestRunner, and error formatting.
+ *
+ * Three functions:
+ *   sanitizeTrace(text) - general-purpose, catches headers + URLs + tokens
+ *   sanitizeUrl(url) - strips query params, preserves path
+ *   sanitizeHeaderValue(name, value) - redacts value for sensitive headers
+ */
+const SENSITIVE_HEADER_NAMES = new Set([
+    'authorization',
+    'cookie',
+    'set-cookie',
+    'x-csrf-token',
+    'x-xsrf-token',
+    'proxy-authorization',
+    'x-api-key',
+    'x-auth-token',
+]);
+const REDACTED = '[REDACTED]';
+// ── sanitizeUrl ─────────────────────────────────────────────────
+/**
+ * Strip query parameters from a URL. Preserves path and fragment.
+ * Handles malformed URLs gracefully (returns input unchanged if unparseable).
+ */
+export function sanitizeUrl(url) {
+    if (!url)
+        return url;
+    try {
+        const parsed = new URL(url);
+        // Clear all query params
+        parsed.search = '';
+        return parsed.toString();
+    }
+    catch {
+        // Fallback: strip everything after '?'
+        const queryIdx = url.indexOf('?');
+        if (queryIdx === -1)
+            return url;
+        const fragIdx = url.indexOf('#');
+        if (fragIdx !== -1 && fragIdx < queryIdx)
+            return url;
+        return fragIdx > queryIdx ? url.slice(0, queryIdx) + url.slice(fragIdx) : url.slice(0, queryIdx);
+    }
+}
+// ── sanitizeHeaderValue ─────────────────────────────────────────
+/**
+ * Redact the value of sensitive headers. Non-sensitive headers pass through.
+ * Case-insensitive header name matching.
+ */
+export function sanitizeHeaderValue(name, value) {
+    if (SENSITIVE_HEADER_NAMES.has(name.toLowerCase())) {
+        return REDACTED;
+    }
+    return value;
+}
+// ── sanitizeTrace ───────────────────────────────────────────────
+// Patterns for common sensitive values in trace text
+const HEADER_VALUE_PATTERN = /^(\s*(?:Authorization|Cookie|Set-Cookie|X-CSRF-Token|X-XSRF-Token|Proxy-Authorization|X-Api-Key|X-Auth-Token)\s*:\s*)(.+)$/gim;
+const URL_QUERY_PATTERN = /https?:\/\/[^\s"']+\?[^\s"']+/gi;
+const BEARER_PATTERN = /Bearer\s+[A-Za-z0-9._~+/=-]+/gi;
+const JWT_LIKE_PATTERN = /eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g;
+/**
+ * General-purpose trace sanitizer. Catches:
+ * - Header values (Authorization: Bearer xxx -> Authorization: [REDACTED])
+ * - URL query params (https://example.com?token=abc -> https://example.com)
+ * - Bearer tokens
+ * - JWT-like strings
+ *
+ * Handles multiline input. Returns empty string for null/undefined input.
+ */
+export function sanitizeTrace(text) {
+    if (!text)
+        return '';
+    let result = text;
+    // Redact header values (must be first to catch Authorization: Bearer xxx)
+    result = result.replace(HEADER_VALUE_PATTERN, `$1${REDACTED}`);
+    // Redact Bearer tokens not already caught by header patterns
+    result = result.replace(BEARER_PATTERN, `Bearer ${REDACTED}`);
+    // Redact JWTs
+    result = result.replace(JWT_LIKE_PATTERN, `${REDACTED}`);
+    // Strip query params from URLs
+    result = result.replace(URL_QUERY_PATTERN, (match) => sanitizeUrl(match));
+    return result;
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Core type definitions for har-o-scope.
+ * No DOM dependencies. Used by library, CLI, and Web Worker.
+ */
+import type { Har, Entry, Header } from 'har-format';
+export type ResourceType = 'document' | 'script' | 'stylesheet' | 'image' | 'font' | 'media' | 'xhr' | 'fetch' | 'websocket' | 'other';
+export interface NormalizedTimings {
+    blocked: number;
+    dns: number;
+    connect: number;
+    ssl: number;
+    send: number;
+    wait: number;
+    receive: number;
+    total: number;
+}
+export interface NormalizedEntry {
+    /** Original HAR entry */
+    entry: Entry;
+    /** Milliseconds since the first entry's startedDateTime */
+    startTimeMs: number;
+    /** Total request duration in ms (sum of all timing phases) */
+    totalDuration: number;
+    /** Resolved transfer size: transferSize > 0 ? transferSize : content.size */
+    transferSizeResolved: number;
+    /** Resolved content size from response.content.size */
+    contentSize: number;
+    /** Parsed timings with -1 replaced by 0 */
+    timings: NormalizedTimings;
+    /** Detected resource type */
+    resourceType: ResourceType;
+    /** True if this looks like a long-poll (wait > 25s + small body, or SSE) */
+    isLongPoll: boolean;
+    /** True if this is a WebSocket connection */
+    isWebSocket: boolean;
+    /** HTTP version string from the request */
+    httpVersion: string;
+}
+export type IssueSeverity = 'info' | 'warning' | 'critical';
+export type IssueCategory = 'server' | 'network' | 'client' | 'optimization' | 'security' | 'errors' | 'informational' | 'performance';
+export interface Finding {
+    /** Rule ID that produced this finding */
+    ruleId: string;
+    /** Issue category */
+    category: IssueCategory;
+    /** Final severity (after escalation) */
+    severity: IssueSeverity;
+    /** Human-readable title (interpolated) */
+    title: string;
+    /** Detailed description (interpolated) */
+    description: string;
+    /** Fix recommendation (interpolated) */
+    recommendation: string;
+    /** Indices into the NormalizedEntry array */
+    affectedEntries: number[];
+    /** Computed impact value */
+    impact: number;
+}
+export interface RootCauseResult {
+    client: number;
+    network: number;
+    server: number;
+}
+export interface AnalysisWarning {
+    code: string;
+    message: string;
+    help: string;
+    docsUrl: string;
+}
+export interface AnalysisMetadata {
+    rulesEvaluated: number;
+    customRulesLoaded: number;
+    analysisTimeMs: number;
+    totalRequests: number;
+    totalTimeMs: number;
+}
+export interface AnalysisResult {
+    /** Normalized entries */
+    entries: NormalizedEntry[];
+    /** Detected findings */
+    findings: Finding[];
+    /** Root cause classification */
+    rootCause: RootCauseResult;
+    /** Non-fatal warnings encountered during analysis */
+    warnings: AnalysisWarning[];
+    /** Analysis metadata */
+    metadata: AnalysisMetadata;
+}
+export interface AnalysisOptions {
+    /** Path to custom YAML rules file or directory */
+    customRules?: string;
+    /** Custom rules as parsed YAML objects */
+    customRulesData?: unknown[];
+    /** Disable built-in rules */
+    noBuiltin?: boolean;
+    /** Minimum severity to include in findings */
+    minSeverity?: IssueSeverity;
+}
+export interface ScoreDeduction {
+    reason: string;
+    points: number;
+}
+export interface ScoreBreakdown {
+    findingDeductions: ScoreDeduction[];
+    timingPenalty: number;
+    volumePenalty: number;
+    confidenceMultiplier: number;
+    totalDeductions: number;
+}
+export interface HealthScore {
+    score: number;
+    breakdown: ScoreBreakdown;
+}
+export interface TimingDelta {
+    urlPattern: string;
+    beforeCount: number;
+    afterCount: number;
+    beforeAvgMs: number;
+    afterAvgMs: number;
+    deltaMs: number;
+    deltaPercent: number;
+}
+export interface FindingDelta {
+    ruleId: string;
+    beforeSeverity: IssueSeverity;
+    afterSeverity: IssueSeverity;
+    beforeCount: number;
+    afterCount: number;
+}
+export interface DiffResult {
+    scoreDelta: number;
+    newFindings: Finding[];
+    resolvedFindings: Finding[];
+    persistedFindings: FindingDelta[];
+    timingDeltas: TimingDelta[];
+    requestCountDelta: number;
+    totalTimeDelta: number;
+}
+export type SanitizeMode = 'aggressive' | 'selective';
+export interface SanitizeOptions {
+    mode: SanitizeMode;
+    /** Categories to sanitize in selective mode */
+    categories?: SanitizeCategory[];
+}
+export type SanitizeCategory = 'cookies' | 'auth-headers' | 'query-params' | 'response-cookies' | 'jwt-signatures' | 'high-entropy';
+export interface ValidationError {
+    code: string;
+    message: string;
+    line?: number;
+    column?: number;
+    help: string;
+    docsUrl: string;
+    suggestion?: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+}
+export type { Har, Entry, Header };
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"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"}

package/dist/lib/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/unbatched-detect.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Unbatched API detection: TypeScript rule (not YAML-expressible).
+ * Groups requests by normalized URL path, flags 5+ requests in a 2-second window.
+ */
+import type { NormalizedEntry, Finding } from './types.js';
+export declare function detectUnbatchedApis(entries: NormalizedEntry[]): Finding | null;
+//# sourceMappingURL=unbatched-detect.d.ts.map

package/dist/lib/unbatched-detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unbatched-detect.d.ts","sourceRoot":"","sources":["../../src/lib/unbatched-detect.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAM1D,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,OAAO,GAAG,IAAI,CAgE9E"}

package/dist/lib/unbatched-detect.js

@@ -0,0 +1,59 @@
+import { normalizeUrlForGrouping } from './diff.js';
+const MIN_COUNT = 5;
+const WINDOW_MS = 2000;
+export function detectUnbatchedApis(entries) {
+    // Group by normalized URL pattern
+    const groups = new Map();
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        if (entry.isWebSocket || entry.isLongPoll)
+            continue;
+        const url = entry.entry.request?.url;
+        if (!url)
+            continue;
+        const pattern = normalizeUrlForGrouping(url);
+        const existing = groups.get(pattern);
+        if (existing) {
+            existing.push(i);
+        }
+        else {
+            groups.set(pattern, [i]);
+        }
+    }
+    // For each group with 5+ entries, check time-window clustering
+    const affectedIndices = [];
+    for (const [, indices] of groups) {
+        if (indices.length < MIN_COUNT)
+            continue;
+        // Sort by start time
+        const sorted = [...indices].sort((a, b) => entries[a].startTimeMs - entries[b].startTimeMs);
+        // Sliding window: find clusters of MIN_COUNT+ within WINDOW_MS
+        let windowStart = 0;
+        for (let windowEnd = 0; windowEnd < sorted.length; windowEnd++) {
+            while (entries[sorted[windowEnd]].startTimeMs - entries[sorted[windowStart]].startTimeMs > WINDOW_MS) {
+                windowStart++;
+            }
+            if (windowEnd - windowStart + 1 >= MIN_COUNT) {
+                // Add all entries in this cluster
+                for (let j = windowStart; j <= windowEnd; j++) {
+                    if (!affectedIndices.includes(sorted[j])) {
+                        affectedIndices.push(sorted[j]);
+                    }
+                }
+            }
+        }
+    }
+    if (affectedIndices.length < MIN_COUNT)
+        return null;
+    const count = affectedIndices.length;
+    return {
+        ruleId: 'unbatched-api-calls',
+        category: 'performance',
+        severity: count >= 10 ? 'critical' : 'warning',
+        title: `${count} unbatched API call${count !== 1 ? 's' : ''}`,
+        description: `${count} requests to similar API endpoints were made within short time windows. Batching these requests would reduce round-trips and improve performance.`,
+        recommendation: 'Batch multiple API calls into a single request where the API supports it. Use debouncing or request coalescing for repeated similar calls.',
+        affectedEntries: affectedIndices,
+        impact: 0,
+    };
+}

package/dist/lib/validator.d.ts

@@ -0,0 +1,4 @@
+import type { ValidationResult } from './types.js';
+import type { SharedConditionsFile } from './schema.js';
+export declare function validate(yamlContent: string, sharedConditions?: SharedConditionsFile): ValidationResult;
+//# sourceMappingURL=validator.d.ts.map

package/dist/lib/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/lib/validator.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,gBAAgB,EAAmB,MAAM,YAAY,CAAA;AACnE,OAAO,KAAK,EAMV,oBAAoB,EACrB,MAAM,aAAa,CAAA;AA8RpB,wBAAgB,QAAQ,CACtB,WAAW,EAAE,MAAM,EACnB,gBAAgB,CAAC,EAAE,oBAAoB,GACtC,gBAAgB,CA+KlB"}