windows-exe-decompiler-mcp-server 0.1.0

package/dist/cache-manager.js

@@ -0,0 +1,454 @@
+/**
+ * Cache Manager
+ * Implements cache key generation and three-tier caching architecture
+ * Requirements: 20.1, 20.2, 20.3, 20.4, 20.5
+ */
+import crypto from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+/**
+ * LRU Cache implementation for memory caching
+ */
+class LRUCache {
+    cache;
+    maxSize;
+    ttlMs;
+    constructor(maxSize, ttlMs) {
+        this.cache = new Map();
+        this.maxSize = maxSize;
+        this.ttlMs = ttlMs;
+    }
+    getWithMeta(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return null;
+        const now = Date.now();
+        // Check if expired
+        if (now - entry.insertedAt > this.ttlMs) {
+            this.cache.delete(key);
+            return null;
+        }
+        // Check absolute source expiration (if available)
+        if (entry.expiresAtMs && now > entry.expiresAtMs) {
+            this.cache.delete(key);
+            return null;
+        }
+        // Move to end (most recently used)
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+        return {
+            value: entry.value,
+            createdAt: entry.createdAt,
+            expiresAt: entry.expiresAt,
+            sampleSha256: entry.sampleSha256,
+        };
+    }
+    get(key) {
+        const entry = this.getWithMeta(key);
+        if (!entry) {
+            return null;
+        }
+        return entry.value;
+    }
+    set(key, value, options) {
+        // Remove if exists (to update position)
+        this.cache.delete(key);
+        // Evict oldest if at capacity
+        if (this.cache.size >= this.maxSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey) {
+                this.cache.delete(firstKey);
+            }
+        }
+        const createdAt = options?.createdAt || new Date().toISOString();
+        const expiresAt = options?.expiresAt;
+        const expiresAtMs = expiresAt ? new Date(expiresAt).getTime() : undefined;
+        this.cache.set(key, {
+            value,
+            insertedAt: Date.now(),
+            createdAt,
+            expiresAt,
+            expiresAtMs: Number.isNaN(expiresAtMs) ? undefined : expiresAtMs,
+            sampleSha256: options?.sampleSha256,
+        });
+    }
+    clear() {
+        this.cache.clear();
+    }
+}
+/**
+ * File System Cache implementation
+ */
+class FileSystemCache {
+    cacheDir;
+    ttlMs;
+    constructor(cacheDir, ttlMs) {
+        this.cacheDir = cacheDir;
+        this.ttlMs = ttlMs;
+    }
+    getCachePath(key) {
+        // Use first 2 chars for bucketing to avoid too many files in one directory
+        const bucket = key.substring(6, 8); // Skip "cache:" prefix
+        return path.join(this.cacheDir, bucket, `${key}.json`);
+    }
+    async getWithMeta(key) {
+        try {
+            const cachePath = this.getCachePath(key);
+            const content = await fs.readFile(cachePath, 'utf-8');
+            const cached = JSON.parse(content);
+            // Check if expired
+            if (cached.expiresAt && new Date(cached.expiresAt) < new Date()) {
+                await fs.unlink(cachePath).catch(() => { }); // Ignore errors
+                return null;
+            }
+            return {
+                data: cached.data,
+                createdAt: cached.createdAt,
+                expiresAt: cached.expiresAt,
+                sampleSha256: cached.sampleSha256,
+            };
+        }
+        catch (error) {
+            // File doesn't exist or can't be read
+            return null;
+        }
+    }
+    async get(key) {
+        const cached = await this.getWithMeta(key);
+        if (!cached) {
+            return null;
+        }
+        return cached.data;
+    }
+    async set(key, data, ttlMs, sampleSha256) {
+        try {
+            const cachePath = this.getCachePath(key);
+            const cacheDir = path.dirname(cachePath);
+            // Ensure directory exists
+            await fs.mkdir(cacheDir, { recursive: true });
+            const cached = {
+                key,
+                data,
+                createdAt: new Date().toISOString(),
+                expiresAt: new Date(Date.now() + (ttlMs || this.ttlMs)).toISOString(),
+                sampleSha256,
+            };
+            await fs.writeFile(cachePath, JSON.stringify(cached), 'utf-8');
+        }
+        catch (error) {
+            // Ignore write errors (cache is optional)
+            console.warn(`Failed to write cache to filesystem: ${error}`);
+        }
+    }
+}
+/**
+ * Cache Manager with three-tier architecture
+ *
+ * Requirements: 20.3, 20.4, 20.5, 26.1 (cache prewarming)
+ *
+ * Architecture:
+ * - L1: Memory cache (LRU, 5 minutes TTL)
+ * - L2: File system cache (30 days TTL)
+ * - L3: Database cache
+ */
+export class CacheManager {
+    memoryCache;
+    fsCache;
+    db;
+    prewarmInProgress = false;
+    constructor(cacheDir, db) {
+        // L1: Memory cache - 1000 items, 5 minutes TTL
+        this.memoryCache = new LRUCache(1000, 5 * 60 * 1000);
+        // L2: File system cache - 30 days TTL
+        this.fsCache = new FileSystemCache(cacheDir, 30 * 24 * 60 * 60 * 1000);
+        // L3: Database cache (optional)
+        this.db = db || null;
+    }
+    /**
+     * Get cached result from three-tier cache
+     *
+     * Requirements: 20.3
+     *
+     * Algorithm:
+     * 1. Check L1 (memory cache)
+     * 2. If miss, check L2 (file system cache) and populate L1
+     * 3. If miss, check L3 (database cache) and populate L1 and L2
+     * 4. Return null if not found in any layer
+     *
+     * @param key - Cache key
+     * @returns Cached data or null if not found
+     */
+    async getCachedResult(key) {
+        const cached = await this.getCachedResultWithMetadata(key);
+        return cached?.data ?? null;
+    }
+    /**
+     * Get cached result with hit metadata for observability.
+     */
+    async getCachedResultWithMetadata(key) {
+        // L1: Check memory cache
+        const memoryResult = this.memoryCache.getWithMeta(key);
+        if (memoryResult !== null) {
+            return {
+                data: memoryResult.value,
+                metadata: {
+                    key,
+                    tier: 'memory',
+                    createdAt: memoryResult.createdAt,
+                    expiresAt: memoryResult.expiresAt,
+                    fetchedAt: new Date().toISOString(),
+                    sampleSha256: memoryResult.sampleSha256,
+                },
+            };
+        }
+        // L2: Check file system cache
+        const fsResult = await this.fsCache.getWithMeta(key);
+        if (fsResult !== null) {
+            // Populate L1
+            this.memoryCache.set(key, fsResult.data, {
+                createdAt: fsResult.createdAt,
+                expiresAt: fsResult.expiresAt,
+                sampleSha256: fsResult.sampleSha256,
+            });
+            return {
+                data: fsResult.data,
+                metadata: {
+                    key,
+                    tier: 'filesystem',
+                    createdAt: fsResult.createdAt,
+                    expiresAt: fsResult.expiresAt,
+                    fetchedAt: new Date().toISOString(),
+                    sampleSha256: fsResult.sampleSha256,
+                },
+            };
+        }
+        // L3: Check database cache
+        if (this.db) {
+            const cached = await this.db.getCachedResult(key);
+            if (cached) {
+                // Check if expired
+                if (cached.expiresAt && new Date(cached.expiresAt) < new Date()) {
+                    return null;
+                }
+                let remainingTtlMs;
+                if (cached.expiresAt) {
+                    const remaining = new Date(cached.expiresAt).getTime() - Date.now();
+                    if (remaining > 0) {
+                        remainingTtlMs = remaining;
+                    }
+                }
+                // Populate L1 and L2
+                this.memoryCache.set(key, cached.data, {
+                    createdAt: cached.createdAt,
+                    expiresAt: cached.expiresAt,
+                    sampleSha256: cached.sampleSha256,
+                });
+                await this.fsCache.set(key, cached.data, remainingTtlMs, cached.sampleSha256);
+                return {
+                    data: cached.data,
+                    metadata: {
+                        key,
+                        tier: 'database',
+                        createdAt: cached.createdAt,
+                        expiresAt: cached.expiresAt,
+                        fetchedAt: new Date().toISOString(),
+                        sampleSha256: cached.sampleSha256,
+                    },
+                };
+            }
+        }
+        return null;
+    }
+    /**
+     * Set cached result in all three tiers
+     *
+     * Requirements: 20.4
+     *
+     * Algorithm:
+     * 1. Store in L1 (memory cache)
+     * 2. Store in L2 (file system cache)
+     * 3. Store in L3 (database cache) if available
+     *
+     * @param key - Cache key
+     * @param data - Data to cache
+     * @param ttl - Time to live in milliseconds (optional)
+     */
+    async setCachedResult(key, data, ttl, sampleSha256) {
+        // L1: Store in memory cache
+        this.memoryCache.set(key, data, { sampleSha256 });
+        // L2: Store in file system cache
+        await this.fsCache.set(key, data, ttl, sampleSha256);
+        // L3: Store in database cache
+        if (this.db) {
+            const expiresAt = ttl ? new Date(Date.now() + ttl).toISOString() : undefined;
+            await this.db.setCachedResult(key, data, expiresAt, sampleSha256);
+        }
+    }
+    /**
+     * Clear all caches
+     */
+    clearAll() {
+        this.memoryCache.clear();
+    }
+    /**
+     * Prewarm cache by loading frequently accessed data into memory
+     *
+     * Requirements: 26.1 (cache prewarming)
+     *
+     * Strategy:
+     * 1. Load recent cache entries from database
+     * 2. Populate L1 (memory) and L2 (filesystem) caches
+     * 3. Prioritize entries with high access frequency
+     *
+     * @param maxEntries - Maximum number of entries to prewarm (default: 100)
+     */
+    async prewarmCache(maxEntries = 100) {
+        if (this.prewarmInProgress) {
+            return 0; // Already prewarming
+        }
+        this.prewarmInProgress = true;
+        let prewarmedCount = 0;
+        try {
+            if (!this.db) {
+                return 0; // No database to prewarm from
+            }
+            // Get recent cache entries from database
+            const recentEntries = await this.db.getRecentCacheEntries(maxEntries);
+            // Load into memory and filesystem caches
+            for (const entry of recentEntries) {
+                try {
+                    // Skip expired entries
+                    if (entry.expires_at && new Date(entry.expires_at) < new Date()) {
+                        continue;
+                    }
+                    // Parse data
+                    const data = JSON.parse(entry.data);
+                    // Populate L1 (memory cache)
+                    this.memoryCache.set(entry.key, data);
+                    // Populate L2 (filesystem cache) - async, don't wait
+                    this.fsCache.set(entry.key, data).catch(() => {
+                        // Ignore filesystem errors during prewarming
+                    });
+                    prewarmedCount++;
+                }
+                catch (error) {
+                    // Skip invalid entries
+                    continue;
+                }
+            }
+            return prewarmedCount;
+        }
+        finally {
+            this.prewarmInProgress = false;
+        }
+    }
+    /**
+     * Prewarm cache for a specific sample
+     * Loads all cached results for a sample into memory
+     *
+     * Requirements: 26.1 (cache prewarming)
+     *
+     * @param sampleSha256 - SHA256 hash of the sample
+     * @returns Number of entries prewarmed
+     */
+    async prewarmSampleCache(sampleSha256) {
+        if (!this.db) {
+            return 0;
+        }
+        let prewarmedCount = 0;
+        // Get all cache entries for this sample
+        const sampleEntries = await this.db.getCacheEntriesBySample(sampleSha256);
+        for (const entry of sampleEntries) {
+            try {
+                // Skip expired entries
+                if (entry.expires_at && new Date(entry.expires_at) < new Date()) {
+                    continue;
+                }
+                // Parse data
+                const data = JSON.parse(entry.data);
+                // Populate L1 (memory cache)
+                this.memoryCache.set(entry.key, data);
+                prewarmedCount++;
+            }
+            catch (error) {
+                // Skip invalid entries
+                continue;
+            }
+        }
+        return prewarmedCount;
+    }
+}
+/**
+ * Generate deterministic cache key from parameters
+ *
+ * Requirements: 20.1, 20.2
+ *
+ * Algorithm:
+ * 1. Normalize arguments (sort keys, remove defaults)
+ * 2. Create canonical representation
+ * 3. Generate SHA256 hash
+ *
+ * @param params - Cache key parameters
+ * @returns Cache key string in format "cache:<sha256>"
+ */
+export function generateCacheKey(params) {
+    // Create normalized object with sorted keys
+    const normalized = {
+        sampleSha256: params.sampleSha256,
+        toolName: params.toolName,
+        toolVersion: params.toolVersion,
+        args: normalizeArgs(params.args),
+        ...(params.rulesetVersion && { rulesetVersion: params.rulesetVersion })
+    };
+    // Sort keys at top level to ensure deterministic order
+    const sortedKeys = Object.keys(normalized).sort();
+    const sortedNormalized = sortedKeys.reduce((acc, key) => {
+        acc[key] = normalized[key];
+        return acc;
+    }, {});
+    // Generate canonical JSON string
+    const keyString = JSON.stringify(sortedNormalized);
+    // Generate SHA256 hash
+    const hash = crypto.createHash('sha256').update(keyString).digest('hex');
+    return `cache:${hash}`;
+}
+/**
+ * Normalize arguments for cache key generation
+ *
+ * Requirements: 20.2
+ *
+ * Normalization rules:
+ * 1. Sort object keys recursively
+ * 2. Remove null and undefined values
+ * 3. Recursively normalize nested objects
+ * 4. Preserve arrays as-is (order matters)
+ *
+ * @param args - Arguments object to normalize
+ * @returns Normalized arguments object
+ */
+export function normalizeArgs(args) {
+    // Handle null/undefined
+    if (args === null || args === undefined) {
+        return {};
+    }
+    // Sort keys and filter out null/undefined values
+    const sortedKeys = Object.keys(args).sort();
+    const normalized = sortedKeys.reduce((acc, key) => {
+        const value = args[key];
+        // Skip null and undefined values
+        if (value === null || value === undefined) {
+            return acc;
+        }
+        // Recursively normalize nested objects
+        if (typeof value === 'object' && !Array.isArray(value)) {
+            acc[key] = normalizeArgs(value);
+        }
+        else {
+            // Keep primitives and arrays as-is
+            acc[key] = value;
+        }
+        return acc;
+    }, {});
+    return normalized;
+}
+//# sourceMappingURL=cache-manager.js.map

package/dist/confidence-semantics.d.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+export declare const ConfidenceSemanticsSchema: z.ZodObject<{
+    score_kind: z.ZodEnum<["heuristic_reconstruction", "runtime_correlation", "naming_resolution", "report_assessment"]>;
+    score: z.ZodNullable<z.ZodNumber>;
+    band: z.ZodEnum<["none", "low", "medium", "high"]>;
+    calibrated: z.ZodBoolean;
+    meaning: z.ZodString;
+    compare_within: z.ZodString;
+    caution: z.ZodString;
+    acceptance_rule: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    drivers: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    score: number | null;
+    score_kind: "heuristic_reconstruction" | "runtime_correlation" | "naming_resolution" | "report_assessment";
+    band: "high" | "none" | "low" | "medium";
+    calibrated: boolean;
+    meaning: string;
+    compare_within: string;
+    caution: string;
+    drivers: string[];
+    acceptance_rule?: string | null | undefined;
+}, {
+    score: number | null;
+    score_kind: "heuristic_reconstruction" | "runtime_correlation" | "naming_resolution" | "report_assessment";
+    band: "high" | "none" | "low" | "medium";
+    calibrated: boolean;
+    meaning: string;
+    compare_within: string;
+    caution: string;
+    drivers: string[];
+    acceptance_rule?: string | null | undefined;
+}>;
+export type ConfidenceSemantics = z.infer<typeof ConfidenceSemanticsSchema>;
+export declare function confidenceBand(score: number | null | undefined): z.infer<typeof ConfidenceSemanticsSchema>['band'];
+export declare function buildReconstructionConfidenceSemantics(input: {
+    score: number;
+    breakdown: {
+        decompile: number;
+        cfg: number;
+        assembly: number;
+        context: number;
+    };
+    runtimeConfidence?: number | null;
+}): ConfidenceSemantics;
+export declare function buildRuntimeConfidenceSemantics(input: {
+    score: number | null | undefined;
+    matchedApis?: string[];
+    matchedStages?: string[];
+    matchedMemoryRegions?: string[];
+    executed?: boolean;
+    evidenceSources?: string[];
+}): ConfidenceSemantics | null;
+export declare function buildNamingConfidenceSemantics(input: {
+    resolutionSource: 'rule' | 'llm' | 'hybrid' | 'unresolved';
+    renameConfidence?: number | null;
+    llmConfidence?: number | null;
+    ruleBasedName?: string | null;
+    validatedName?: string | null;
+}): ConfidenceSemantics;
+export declare function buildReportConfidenceSemantics(input: {
+    score: number;
+    evidenceScope: 'all' | 'latest' | 'session';
+    runtimeLayers?: string[];
+    executedTracePresent?: boolean;
+}): ConfidenceSemantics;
+//# sourceMappingURL=confidence-semantics.d.ts.map

package/dist/confidence-semantics.js

@@ -0,0 +1,122 @@
+import { z } from 'zod';
+export const ConfidenceSemanticsSchema = z.object({
+    score_kind: z.enum([
+        'heuristic_reconstruction',
+        'runtime_correlation',
+        'naming_resolution',
+        'report_assessment',
+    ]),
+    score: z.number().min(0).max(1).nullable(),
+    band: z.enum(['none', 'low', 'medium', 'high']),
+    calibrated: z.boolean(),
+    meaning: z.string(),
+    compare_within: z.string(),
+    caution: z.string(),
+    acceptance_rule: z.string().nullable().optional(),
+    drivers: z.array(z.string()),
+});
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+export function confidenceBand(score) {
+    if (typeof score !== 'number' || Number.isNaN(score)) {
+        return 'none';
+    }
+    if (score >= 0.75) {
+        return 'high';
+    }
+    if (score >= 0.45) {
+        return 'medium';
+    }
+    return 'low';
+}
+export function buildReconstructionConfidenceSemantics(input) {
+    const drivers = [
+        input.breakdown.decompile > 0 ? `decompile=${input.breakdown.decompile.toFixed(2)}` : '',
+        input.breakdown.cfg > 0 ? `cfg=${input.breakdown.cfg.toFixed(2)}` : '',
+        input.breakdown.assembly > 0 ? `assembly=${input.breakdown.assembly.toFixed(2)}` : '',
+        input.breakdown.context > 0 ? `context=${input.breakdown.context.toFixed(2)}` : '',
+        typeof input.runtimeConfidence === 'number' && input.runtimeConfidence > 0
+            ? `runtime_correlation=${input.runtimeConfidence.toFixed(2)}`
+            : '',
+    ].filter((item) => item.length > 0);
+    return {
+        score_kind: 'heuristic_reconstruction',
+        score: clamp(input.score, 0, 1),
+        band: confidenceBand(input.score),
+        calibrated: false,
+        meaning: 'Heuristic evidence score for reconstruction quality. Higher values mean stronger decompile/CFG/assembly/context support, not probability of semantic correctness.',
+        compare_within: 'Compare across functions produced by the same tool version and evidence scope, not across unrelated tools or datasets.',
+        caution: 'Treat as ranking-oriented guidance. Low-level helper functions can still be correct at lower scores, and large complex functions can still contain wrong details at high scores.',
+        drivers,
+    };
+}
+export function buildRuntimeConfidenceSemantics(input) {
+    if (typeof input.score !== 'number' || Number.isNaN(input.score)) {
+        return null;
+    }
+    const drivers = [
+        (input.matchedApis || []).length > 0 ? `matched_apis=${(input.matchedApis || []).length}` : '',
+        (input.matchedStages || []).length > 0 ? `matched_stages=${(input.matchedStages || []).length}` : '',
+        (input.matchedMemoryRegions || []).length > 0
+            ? `matched_regions=${(input.matchedMemoryRegions || []).length}`
+            : '',
+        input.executed ? 'executed_trace=yes' : 'executed_trace=no',
+        (input.evidenceSources || []).length > 0
+            ? `sources=${(input.evidenceSources || []).slice(0, 3).join(',')}`
+            : '',
+    ].filter((item) => item.length > 0);
+    return {
+        score_kind: 'runtime_correlation',
+        score: clamp(input.score, 0, 1),
+        band: confidenceBand(input.score),
+        calibrated: false,
+        meaning: 'Heuristic overlap score between this function and runtime evidence. Higher values mean more API/stage/region corroboration, not proof that the entire function executed.',
+        compare_within: 'Compare across functions under the same evidence_scope and selected runtime artifacts.',
+        caution: 'String-heavy memory snapshots and shared helper routines can inflate overlap without proving exact control-flow execution.',
+        drivers,
+    };
+}
+export function buildNamingConfidenceSemantics(input) {
+    const baseScore = input.resolutionSource === 'llm'
+        ? input.llmConfidence ?? null
+        : input.renameConfidence ?? input.llmConfidence ?? null;
+    const drivers = [
+        input.ruleBasedName ? `rule_name=${input.ruleBasedName}` : '',
+        input.validatedName ? `validated_name=${input.validatedName}` : '',
+        typeof input.renameConfidence === 'number' ? `rule_score=${input.renameConfidence.toFixed(2)}` : '',
+        typeof input.llmConfidence === 'number' ? `llm_score=${input.llmConfidence.toFixed(2)}` : '',
+        `resolution_source=${input.resolutionSource}`,
+    ].filter((item) => item.length > 0);
+    return {
+        score_kind: 'naming_resolution',
+        score: typeof baseScore === 'number' ? clamp(baseScore, 0, 1) : null,
+        band: confidenceBand(baseScore),
+        calibrated: false,
+        meaning: 'Semantic naming confidence for the chosen label. It ranks naming support strength, not certainty that the recovered name matches the original source identifier.',
+        compare_within: 'Compare across names generated by the same naming pipeline version. Rule-based and LLM-suggested scores are still heuristic.',
+        caution: 'A validated name can still be approximate. Original developer naming cannot be reconstructed from this score alone.',
+        acceptance_rule: 'Rule-based names currently take priority. Pure LLM suggestions are promoted to validated_name only when llm_confidence >= 0.62.',
+        drivers,
+    };
+}
+export function buildReportConfidenceSemantics(input) {
+    const drivers = [
+        `evidence_scope=${input.evidenceScope}`,
+        (input.runtimeLayers || []).length > 0
+            ? `runtime_layers=${(input.runtimeLayers || []).join('>')}`
+            : 'runtime_layers=static_only',
+        input.executedTracePresent ? 'executed_trace=yes' : 'executed_trace=no',
+    ];
+    return {
+        score_kind: 'report_assessment',
+        score: clamp(input.score, 0, 1),
+        band: confidenceBand(input.score),
+        calibrated: false,
+        meaning: 'Assessment confidence for the generated report or triage summary. It indicates evidence strength and corroboration depth, not a calibrated threat probability.',
+        compare_within: 'Compare within the same report mode, tool version, and evidence scope.',
+        caution: 'Threat or intent judgments remain evidence-sensitive and can shift when scope changes from all to latest/session or when stronger runtime evidence is added.',
+        drivers,
+    };
+}
+//# sourceMappingURL=confidence-semantics.js.map