@aspect-guard/core 0.1.0 → 0.5.0

package/dist/index.d.ts

@@ -72,6 +72,18 @@ interface Finding {
     remediation?: string;
 }
 
+type IntegrityStatus = 'verified' | 'modified' | 'unknown' | 'skipped' | 'error';
+interface IntegrityInfo {
+    status: IntegrityStatus;
+    /** Which parts were modified (if status is 'modified') */
+    modifications?: {
+        manifest: boolean;
+        content: boolean;
+        structure: boolean;
+    };
+    /** Combined hash of this extension */
+    hash?: string;
+}
 interface ScanResult {
     extensionId: string;
     displayName: string;
@@ -82,6 +94,8 @@ interface ScanResult {
     metadata: ExtensionInfo;
     analyzedFiles: number;
     scanDurationMs: number;
+    /** Integrity verification result (only if --verify-integrity is used) */
+    integrity?: IntegrityInfo;
 }
 interface ScanSummary {
     byRiskLevel: Record<RiskLevel, number>;
@@ -129,6 +143,10 @@ interface ScanOptions {
     skipRules?: string[];
     concurrency?: number;
     timeout?: number;
+    /** Enable integrity verification against known-good hashes */
+    verifyIntegrity?: boolean;
+    /** Path to custom hash database */
+    hashDatabasePath?: string;
 }
 interface InspectOptions {
     vsixPath: string;
@@ -139,6 +157,7 @@ interface InspectOptions {
 declare class ExtensionGuardScanner {
     private options;
     private ruleEngine;
+    private hashDatabase;
     constructor(options?: Partial<ScanOptions>);
     scan(options?: Partial<ScanOptions>): Promise<FullScanReport>;
     private scanExtension;
@@ -147,9 +166,46 @@ declare class ExtensionGuardScanner {
     private calculateSummary;
 }
 
+/**
+ * IDE extension paths organized by IDE name.
+ * Each IDE has multiple possible paths to support:
+ * - Different OS (Windows, macOS, Linux)
+ * - Different installation methods (user, system, portable)
+ * - Remote development scenarios (SSH, WSL, containers)
+ *
+ * Paths use these placeholders:
+ * - ~ : User home directory
+ * - %USERPROFILE% : Windows user profile
+ * - %APPDATA% : Windows AppData/Roaming
+ * - %LOCALAPPDATA% : Windows AppData/Local
+ *
+ * References:
+ * - https://code.visualstudio.com/docs/editor/extension-marketplace
+ * - https://code.visualstudio.com/docs/remote/troubleshooting
+ * - https://vscodium.com/
+ * - https://zed.dev/docs/extensions/installing-extensions
+ */
 declare const IDE_PATHS: Record<string, string[]>;
+/**
+ * Expand path placeholders to actual paths
+ */
 declare function expandPath(inputPath: string): string;
+/**
+ * Detect all installed IDE extension paths
+ */
 declare function detectIDEPaths(): DetectedIDE[];
+/**
+ * Get list of all supported IDE names
+ */
+declare function getSupportedIDEs(): string[];
+/**
+ * Check if a specific IDE is installed
+ */
+declare function isIDEInstalled(ideName: string): boolean;
+/**
+ * Get the extension path for a specific IDE
+ */
+declare function getIDEExtensionPath(ideName: string): string | null;
 
 declare function readExtension(extensionPath: string): Promise<ExtensionInfo | null>;
 declare function readExtensionsFromDirectory(directoryPath: string): Promise<ExtensionInfo[]>;
@@ -157,6 +213,17 @@ declare function readExtensionsFromDirectory(directoryPath: string): Promise<Ext
 declare function shouldCollectFile(filePath: string): boolean;
 declare function collectFiles(extensionPath: string): Promise<Map<string, string>>;
 
+/**
+ * Inferred extension category used to adjust finding severity.
+ * Extensions in different categories have different "normal" behaviors.
+ */
+type ExtensionCategory = 'theme' | 'language' | 'ai-assistant' | 'scm' | 'debugger' | 'linter' | 'language-support' | 'developer-tools' | 'remote-development' | 'testing' | 'notebook' | 'general';
+/**
+ * Infer an extension's category from its manifest (package.json).
+ * Uses categories, contributes, keywords, displayName, and description.
+ */
+declare function categorizeExtension(manifest: ExtensionManifest): ExtensionCategory;
+
 interface DetectionRule {
     id: string;
     name: string;
@@ -195,6 +262,165 @@ declare const ruleRegistry: RuleRegistry;
 
 declare function registerBuiltInRules(): void;
 
+/**
+ * All built-in detection rules with their metadata.
+ * Useful for CLI commands that list rules.
+ */
+declare const DETECTION_RULES: DetectionRule[];
+
+/**
+ * Options for adjusting findings.
+ */
+interface AdjustFindingsOptions {
+    /** Publisher name for soft trust check */
+    publisher?: string;
+    /** Full extension ID (publisher.name) for soft trust check */
+    extensionId?: string;
+    /** Skip soft trust adjustments (strict mode) */
+    strictMode?: boolean;
+    /** Map of file paths to file contents for bundle detection */
+    files?: Map<string, string>;
+}
+/**
+ * Adjust findings based on the extension's inferred category and trust status.
+ *
+ * Four layers of adjustment:
+ * 1. Category-based: Expected behaviors for extension type (e.g., AI tools use network)
+ * 2. Soft Trust: Trusted publishers get an additional severity downgrade
+ * 3. Verified Publisher: Verified publishers on marketplace get severity downgrade
+ * 4. Popularity: Extensions with 10M+ downloads get double downgrade, 1M+ get single
+ *
+ * Returns a new array with adjusted findings (original array is not mutated).
+ */
+declare function adjustFindings(findings: Finding[], category: ExtensionCategory, options?: AdjustFindingsOptions): Finding[];
+
+/**
+ * List of well-known, trusted publishers.
+ *
+ * Extensions from these publishers receive "soft trust" treatment:
+ * - Their findings are downgraded one additional severity level
+ * - They are NOT completely bypassed (supply chain attacks can hit anyone)
+ *
+ * This list is intentionally conservative and includes only:
+ * - Major IDE vendors (Microsoft, GitHub)
+ * - Well-established tool vendors with long track records
+ */
+declare const TRUSTED_PUBLISHERS: string[];
+/**
+ * Specific extension IDs that are trusted regardless of publisher.
+ * Use this for known extensions from smaller publishers.
+ */
+declare const TRUSTED_EXTENSION_IDS: string[];
+/**
+ * Check if an extension is from a trusted publisher.
+ */
+declare function isTrustedPublisher(publisher: string): boolean;
+/**
+ * Check if an extension ID is explicitly trusted.
+ */
+declare function isTrustedExtension(extensionId: string): boolean;
+
+/**
+ * List of verified publishers from VS Code Marketplace.
+ *
+ * These publishers have undergone verification by Microsoft and display
+ * a verified badge on the marketplace. Extensions from verified publishers
+ * are treated similarly to trusted publishers.
+ *
+ * Note: This list is maintained manually based on known verified publishers.
+ * In the future, this could be fetched from the marketplace API.
+ */
+declare const VERIFIED_PUBLISHERS: string[];
+/**
+ * Check if a publisher is verified on the marketplace.
+ */
+declare function isVerifiedPublisher(publisher: string): boolean;
+
+/**
+ * List of popular extensions with high download counts.
+ *
+ * Extensions with millions of downloads have been vetted by the community
+ * through widespread usage. Supply chain attacks on these would be extremely
+ * visible and risky for attackers.
+ *
+ * Threshold tiers:
+ * - 10M+ downloads: Highest trust (downgrade by 2 severity levels)
+ * - 1M+ downloads: High trust (downgrade by 1 severity level)
+ *
+ * Note: This data is manually maintained. In the future, this could be
+ * fetched from the marketplace API and cached locally.
+ *
+ * Last updated: 2026-02
+ */
+interface PopularExtension {
+    id: string;
+    downloads: number;
+    tier: 'mega' | 'popular';
+}
+/**
+ * Extensions with 10M+ downloads (mega popular)
+ */
+declare const MEGA_POPULAR_EXTENSIONS: PopularExtension[];
+/**
+ * Extensions with 1M-10M downloads (popular)
+ */
+declare const POPULAR_EXTENSIONS: PopularExtension[];
+/**
+ * All popular extensions combined
+ */
+declare const ALL_POPULAR_EXTENSIONS: PopularExtension[];
+/**
+ * Get popularity tier for an extension.
+ * Returns null if not in the popular extensions list.
+ */
+declare function getPopularityTier(extensionId: string): 'mega' | 'popular' | null;
+/**
+ * Check if an extension is mega popular (10M+ downloads)
+ */
+declare function isMegaPopular(extensionId: string): boolean;
+/**
+ * Check if an extension is popular (1M+ downloads)
+ */
+declare function isPopular(extensionId: string): boolean;
+
+/**
+ * Bundle/Minified File Detector
+ *
+ * Detects if a JavaScript file is bundled/minified output from tools like:
+ * - webpack
+ * - esbuild
+ * - rollup
+ * - parcel
+ * - vite
+ *
+ * Bundled files often trigger false positives because:
+ * - They contain many library dependencies inlined
+ * - Minification creates high-entropy code patterns
+ * - Source maps and comments are stripped
+ */
+interface BundleDetectionResult {
+    isBundled: boolean;
+    confidence: 'high' | 'medium' | 'low';
+    reasons: string[];
+    bundler?: string;
+}
+/**
+ * Detect if a file is a bundled/minified output
+ */
+declare function detectBundle(filePath: string, content: string): BundleDetectionResult;
+/**
+ * Check if a file path looks like a bundled output location
+ */
+declare function isBundleOutputPath(filePath: string): boolean;
+/**
+ * Determine if findings from this file should be treated with reduced severity
+ * because it's likely bundled code (which commonly contains many false positives)
+ */
+declare function shouldReduceSeverityForBundle(filePath: string, content: string): {
+    reduce: boolean;
+    reason?: string;
+};
+
 interface ReporterOptions {
     includeEvidence?: boolean;
     includeSafe?: boolean;
@@ -390,6 +616,137 @@ declare class PolicyEngine {
     private checkMaxDaysSinceUpdate;
 }
 
-declare const VERSION = "0.1.0";
+/**
+ * Extension Integrity Verifier
+ *
+ * Verifies that installed extensions match their known-good hashes.
+ * This detects supply chain attacks where an official extension has been
+ * tampered with after installation or during distribution.
+ *
+ * Verification methods:
+ * 1. File content hash - SHA256 of all JS files concatenated
+ * 2. Manifest hash - SHA256 of package.json
+ * 3. Structure hash - Hash of file list (detects added/removed files)
+ */
+/**
+ * Hash record for a specific extension version
+ */
+interface ExtensionHash {
+    /** Extension ID (publisher.name) */
+    extensionId: string;
+    /** Version string */
+    version: string;
+    /** SHA256 of package.json content */
+    manifestHash: string;
+    /** SHA256 of all JS file contents concatenated (sorted by path) */
+    contentHash: string;
+    /** SHA256 of sorted file path list */
+    structureHash: string;
+    /** Combined hash for quick comparison */
+    combinedHash: string;
+    /** When this hash was recorded */
+    recordedAt: string;
+    /** Source of the hash (marketplace, manual, etc.) */
+    source: 'marketplace' | 'manual' | 'community';
+}
+/**
+ * Result of integrity verification
+ */
+interface IntegrityResult {
+    extensionId: string;
+    version: string;
+    status: 'verified' | 'modified' | 'unknown' | 'error';
+    /** Which parts were modified (if status is 'modified') */
+    modifications?: {
+        manifest: boolean;
+        content: boolean;
+        structure: boolean;
+    };
+    /** The computed hashes */
+    computedHashes?: {
+        manifestHash: string;
+        contentHash: string;
+        structureHash: string;
+        combinedHash: string;
+    };
+    /** The expected hashes (if known) */
+    expectedHashes?: ExtensionHash;
+    /** Error message if status is 'error' */
+    error?: string;
+}
+/**
+ * Compute SHA256 hash of a string
+ */
+declare function sha256(content: string): string;
+/**
+ * Compute hashes for an extension from its files
+ */
+declare function computeExtensionHashes(extensionId: string, version: string, files: Map<string, string>): Omit<ExtensionHash, 'recordedAt' | 'source'>;
+/**
+ * Verify extension integrity against known hashes
+ */
+declare function verifyIntegrity(extensionId: string, version: string, files: Map<string, string>, knownHashes: Map<string, ExtensionHash>): IntegrityResult;
+/**
+ * Create a hash record for an extension (for adding to the database)
+ */
+declare function createHashRecord(extensionId: string, version: string, files: Map<string, string>, source?: ExtensionHash['source']): ExtensionHash;
+
+/**
+ * Known-Good Hash Database
+ *
+ * This module manages the database of known-good extension hashes.
+ * The database can be:
+ * 1. Bundled with the package (for critical extensions)
+ * 2. Downloaded from a remote server (for community-maintained hashes)
+ * 3. Locally maintained by the user
+ *
+ * IMPORTANT: This is a static snapshot. For production use, consider:
+ * - Fetching from VS Code Marketplace API
+ * - Community-maintained hash repository
+ * - User-generated baseline from clean install
+ */
+
+/**
+ * Hash database structure
+ */
+interface HashDatabase {
+    version: string;
+    updatedAt: string;
+    hashes: ExtensionHash[];
+}
+/**
+ * Default path for local hash database
+ */
+declare function getDefaultDatabasePath(): string;
+/**
+ * Load hash database from a JSON file
+ */
+declare function loadHashDatabase(filePath?: string): Map<string, ExtensionHash>;
+/**
+ * Save hash database to a JSON file
+ */
+declare function saveHashDatabase(hashes: Map<string, ExtensionHash>, filePath?: string): void;
+/**
+ * Add or update a hash in the database
+ */
+declare function addHash(hash: ExtensionHash, filePath?: string): void;
+/**
+ * Get a hash from the database
+ */
+declare function getHash(extensionId: string, version: string, filePath?: string): ExtensionHash | undefined;
+/**
+ * Clear the hash cache (useful for testing)
+ */
+declare function clearHashCache(): void;
+/**
+ * Generate a baseline database from currently installed extensions
+ * This is useful for users to create their own trusted baseline
+ */
+declare function generateBaseline(_extensionPaths: string[], _outputPath?: string): Promise<{
+    generated: number;
+    errors: string[];
+}>;
+
+declare const VERSION = "0.5.0";
 
-export { type AuditReport, type DetectedIDE, type DetectionRule, type Evidence, ExtensionGuardScanner, type ExtensionInfo, type ExtensionManifest, type Finding, type FindingCategory, type FullScanReport, IDE_PATHS, type InspectOptions, JsonReporter, MarkdownReporter, type PolicyAction, type PolicyConfig, PolicyEngine, type PolicyRules, type PolicyViolation, type Reporter, type ReporterOptions, type RiskLevel, RuleEngine, type RuleEngineOptions, SEVERITY_ORDER, SarifReporter, type ScanOptions, type ScanResult, type ScanSummary, type Severity, VERSION, collectFiles, compareSeverity, detectIDEPaths, expandPath, isAtLeastSeverity, loadPolicyConfig, readExtension, readExtensionsFromDirectory, registerBuiltInRules, ruleRegistry, shouldCollectFile };
+export { ALL_POPULAR_EXTENSIONS, type AdjustFindingsOptions, type AuditReport, type BundleDetectionResult, DETECTION_RULES, type DetectedIDE, type DetectionRule, type Evidence, type ExtensionCategory, ExtensionGuardScanner, type ExtensionHash, type ExtensionInfo, type ExtensionManifest, type Finding, type FindingCategory, type FullScanReport, type HashDatabase, IDE_PATHS, type InspectOptions, type IntegrityInfo, type IntegrityResult, type IntegrityStatus, JsonReporter, MEGA_POPULAR_EXTENSIONS, MarkdownReporter, POPULAR_EXTENSIONS, type PolicyAction, type PolicyConfig, PolicyEngine, type PolicyRules, type PolicyViolation, type PopularExtension, type Reporter, type ReporterOptions, type RiskLevel, RuleEngine, type RuleEngineOptions, SEVERITY_ORDER, SarifReporter, type ScanOptions, type ScanResult, type ScanSummary, type Severity, TRUSTED_EXTENSION_IDS, TRUSTED_PUBLISHERS, VERIFIED_PUBLISHERS, VERSION, addHash, adjustFindings, categorizeExtension, clearHashCache, collectFiles, compareSeverity, computeExtensionHashes, createHashRecord, detectBundle, detectIDEPaths, expandPath, generateBaseline, getDefaultDatabasePath, getHash, getIDEExtensionPath, getPopularityTier, getSupportedIDEs, isAtLeastSeverity, isBundleOutputPath, isIDEInstalled, isMegaPopular, isPopular, isTrustedExtension, isTrustedPublisher, isVerifiedPublisher, loadHashDatabase, loadPolicyConfig, readExtension, readExtensionsFromDirectory, registerBuiltInRules, ruleRegistry, saveHashDatabase, sha256, shouldCollectFile, shouldReduceSeverityForBundle, verifyIntegrity };