driftdetect-detectors 0.1.0

package/dist/auth/token-handling.js

@@ -0,0 +1,151 @@
+/**
+ * Token Handling Detector - Token pattern detection
+ *
+ * Detects token handling patterns including JWT storage, refresh tokens,
+ * token validation, and secure token practices.
+ *
+ * Flags violations: Insecure token storage, missing refresh logic, exposed tokens.
+ *
+ * @requirements 11.2 - Token handling patterns
+ */
+import { RegexDetector } from '../base/index.js';
+export const TOKEN_STORAGE_PATTERNS = [
+    /localStorage\.setItem\s*\(\s*['"`](?:token|jwt|access_token|auth)/gi,
+    /sessionStorage\.setItem\s*\(\s*['"`](?:token|jwt|access_token|auth)/gi,
+    /document\.cookie\s*=.*(?:token|jwt|access)/gi,
+    /setCookie\s*\([^)]*(?:token|jwt|access)/gi,
+];
+export const SECURE_COOKIE_PATTERNS = [
+    /httpOnly\s*:\s*true/gi,
+    /secure\s*:\s*true/gi,
+    /sameSite\s*:\s*['"`](?:strict|lax)['"`]/gi,
+];
+export const REFRESH_TOKEN_PATTERNS = [
+    /refresh[_-]?token/gi,
+    /refreshToken/gi,
+    /\/api\/(?:auth\/)?refresh/gi,
+    /tokenRefresh/gi,
+    /rotateToken/gi,
+];
+export const TOKEN_VALIDATION_PATTERNS = [
+    /jwt\.verify\s*\(/gi,
+    /verifyToken\s*\(/gi,
+    /validateToken\s*\(/gi,
+    /isTokenValid/gi,
+    /checkToken/gi,
+    /decodeToken\s*\(/gi,
+];
+export const TOKEN_EXTRACTION_PATTERNS = [
+    /(?:req|request)\.headers\s*\[\s*['"`]authorization['"`]\s*\]/gi,
+    /Bearer\s+/gi,
+    /getToken\s*\(/gi,
+    /extractToken/gi,
+    /parseToken/gi,
+];
+export const INSECURE_STORAGE_PATTERNS = [
+    /localStorage\.setItem\s*\(\s*['"`](?:token|jwt|access_token)['"`]/gi,
+];
+export const TOKEN_IN_URL_PATTERNS = [
+    /\?.*token=/gi,
+    /&token=/gi,
+    /url\s*[+=].*token/gi,
+];
+export const TOKEN_LOGGED_PATTERNS = [
+    /console\.log\s*\([^)]*token/gi,
+    /logger\.\w+\s*\([^)]*token/gi,
+    /print\s*\([^)]*token/gi,
+];
+export const EXCLUDED_FILE_PATTERNS = [/\.test\.[jt]sx?$/, /\.spec\.[jt]sx?$/, /node_modules\//, /\.d\.ts$/];
+export function shouldExcludeFile(filePath) {
+    return EXCLUDED_FILE_PATTERNS.some(p => p.test(filePath));
+}
+function isInsideComment(content, index) {
+    const before = content.slice(0, index);
+    const lastNewline = before.lastIndexOf('\n');
+    const line = before.slice(lastNewline + 1);
+    if (line.includes('//') && index - lastNewline - 1 > line.indexOf('//'))
+        return true;
+    return before.lastIndexOf('/*') > before.lastIndexOf('*/');
+}
+function getPosition(content, index) {
+    const before = content.slice(0, index);
+    return { line: before.split('\n').length, column: index - before.lastIndexOf('\n') };
+}
+function detectPatterns(content, file, patterns, type) {
+    const results = [];
+    const lines = content.split('\n');
+    for (const pattern of patterns) {
+        const regex = new RegExp(pattern.source, pattern.flags);
+        let match;
+        while ((match = regex.exec(content)) !== null) {
+            if (isInsideComment(content, match.index))
+                continue;
+            const { line, column } = getPosition(content, match.index);
+            results.push({ type, file, line, column, matchedText: match[0], context: lines[line - 1] || '' });
+        }
+    }
+    return results;
+}
+function detectViolations(content, file, patterns, type, issue, fix) {
+    const violations = [];
+    const lines = content.split('\n');
+    for (const pattern of patterns) {
+        const regex = new RegExp(pattern.source, pattern.flags);
+        let match;
+        while ((match = regex.exec(content)) !== null) {
+            if (isInsideComment(content, match.index))
+                continue;
+            const { line, column } = getPosition(content, match.index);
+            violations.push({
+                type, file, line, column,
+                endLine: line, endColumn: column + match[0].length,
+                value: match[0], issue, suggestedFix: fix,
+                lineContent: lines[line - 1] || '',
+            });
+        }
+    }
+    return violations;
+}
+export function analyzeTokenHandling(content, file) {
+    if (shouldExcludeFile(file)) {
+        return { patterns: [], violations: [], usesSecureStorage: false, hasRefreshLogic: false };
+    }
+    const patterns = [
+        ...detectPatterns(content, file, TOKEN_STORAGE_PATTERNS, 'jwt-storage'),
+        ...detectPatterns(content, file, REFRESH_TOKEN_PATTERNS, 'refresh-token'),
+        ...detectPatterns(content, file, TOKEN_VALIDATION_PATTERNS, 'token-validation'),
+        ...detectPatterns(content, file, TOKEN_EXTRACTION_PATTERNS, 'token-extraction'),
+        ...detectPatterns(content, file, SECURE_COOKIE_PATTERNS, 'secure-cookie'),
+    ];
+    const violations = [
+        ...detectViolations(content, file, INSECURE_STORAGE_PATTERNS, 'insecure-storage', 'Token stored in localStorage is vulnerable to XSS', 'Use httpOnly cookies instead'),
+        ...detectViolations(content, file, TOKEN_IN_URL_PATTERNS, 'token-in-url', 'Token in URL can be leaked via referrer or logs', 'Pass tokens in headers instead'),
+        ...detectViolations(content, file, TOKEN_LOGGED_PATTERNS, 'token-logged', 'Token being logged may expose sensitive data', 'Remove token from logs'),
+    ];
+    const usesSecureStorage = patterns.some(p => p.type === 'secure-cookie');
+    const hasRefreshLogic = patterns.some(p => p.type === 'refresh-token');
+    return { patterns, violations, usesSecureStorage, hasRefreshLogic };
+}
+export class TokenHandlingDetector extends RegexDetector {
+    id = 'auth/token-handling';
+    name = 'Token Handling Detector';
+    description = 'Detects token handling patterns and security issues';
+    category = 'auth';
+    subcategory = 'tokens';
+    supportedLanguages = ['typescript', 'javascript', 'python'];
+    async detect(context) {
+        const { content, file } = context;
+        if (shouldExcludeFile(file))
+            return this.createEmptyResult();
+        const analysis = analyzeTokenHandling(content, file);
+        const confidence = analysis.usesSecureStorage ? 0.9 : 0.75;
+        return this.createResult([], [], confidence);
+    }
+    generateQuickFix() {
+        return null;
+    }
+}
+export function createTokenHandlingDetector() {
+    return new TokenHandlingDetector();
+}
+//# sourceMappingURL=token-handling.js.map

package/dist/auth/token-handling.js.map

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

package/dist/base/ast-detector.d.ts

@@ -0,0 +1,421 @@
+/**
+ * AST Detector - AST-based detection base class
+ *
+ * Provides Tree-sitter query helpers and utilities for AST-based pattern detection.
+ * Extends BaseDetector with specialized methods for traversing and querying ASTs.
+ *
+ * @requirements 6.4 - THE Detector_System SHALL support detection methods: ast, regex, semantic, structural, and custom
+ */
+import type { AST, ASTNode } from 'driftdetect-core';
+import { BaseDetector } from './base-detector.js';
+/**
+ * Pattern definition for AST matching
+ *
+ * Defines criteria for matching AST nodes during detection.
+ */
+export interface ASTPattern {
+    /** Node type to match (e.g., 'FunctionDeclaration', 'ClassDeclaration') */
+    type?: string;
+    /** Text content to match (exact string or regex) */
+    text?: string | RegExp;
+    /** Whether text matching should be exact */
+    exactText?: boolean;
+    /** Child patterns to match */
+    children?: ASTPattern[];
+    /** Minimum number of children required */
+    minChildren?: number;
+    /** Maximum number of children allowed */
+    maxChildren?: number;
+    /** Custom predicate for additional matching logic */
+    predicate?: (node: ASTNode) => boolean;
+    /** Whether to match any descendant (not just direct children) */
+    matchDescendants?: boolean;
+    /** Capture name for extracting matched nodes */
+    capture?: string;
+}
+/**
+ * Result of an AST pattern match
+ */
+export interface ASTMatchResult {
+    /** The matched node */
+    node: ASTNode;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** Captured nodes by name */
+    captures: Map<string, ASTNode>;
+    /** Start position in source */
+    startPosition: {
+        row: number;
+        column: number;
+    };
+    /** End position in source */
+    endPosition: {
+        row: number;
+        column: number;
+    };
+}
+/**
+ * Options for AST traversal
+ */
+export interface TraversalOptions {
+    /** Maximum depth to traverse (undefined = unlimited) */
+    maxDepth?: number;
+    /** Node types to skip during traversal */
+    skipTypes?: string[];
+    /** Whether to include the root node in traversal */
+    includeRoot?: boolean;
+}
+/**
+ * Visitor function for AST traversal
+ *
+ * @param node - Current node being visited
+ * @param parent - Parent node (null for root)
+ * @param depth - Current depth in the tree
+ * @returns false to stop traversal of subtree, undefined to continue
+ */
+export type ASTVisitor = (node: ASTNode, parent: ASTNode | null, depth: number) => boolean | void;
+/**
+ * Abstract base class for AST-based detectors
+ *
+ * Provides Tree-sitter query helpers and utilities for pattern detection
+ * that operates on parsed AST structures.
+ *
+ * @requirements 6.4 - THE Detector_System SHALL support detection methods: ast
+ *
+ * @example
+ * ```typescript
+ * class FunctionNamingDetector extends ASTDetector {
+ *   readonly id = 'structural/function-naming';
+ *   readonly category = 'structural';
+ *   readonly subcategory = 'naming-conventions';
+ *   readonly name = 'Function Naming Detector';
+ *   readonly description = 'Detects function naming patterns';
+ *   readonly supportedLanguages = ['typescript', 'javascript'];
+ *
+ *   async detect(context: DetectionContext): Promise<DetectionResult> {
+ *     if (!context.ast) {
+ *       return this.createEmptyResult();
+ *     }
+ *
+ *     const functions = this.findNodes(context.ast, 'function_declaration');
+ *     // Analyze function naming patterns...
+ *   }
+ *
+ *   generateQuickFix(violation: Violation): QuickFix | null {
+ *     return null;
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class ASTDetector extends BaseDetector {
+    /**
+     * Detection method is always 'ast' for AST-based detectors
+     *
+     * @requirements 6.4 - Detector declares detection method as 'ast'
+     */
+    readonly detectionMethod: "ast";
+    /**
+     * Find all nodes of a specific type in the AST
+     *
+     * Traverses the entire AST and returns all nodes matching the specified type.
+     *
+     * @param ast - The AST to search
+     * @param nodeType - The type of node to find (e.g., 'function_declaration', 'class_declaration')
+     * @returns Array of matching nodes
+     *
+     * @example
+     * ```typescript
+     * const functions = this.findNodes(ast, 'function_declaration');
+     * const classes = this.findNodes(ast, 'class_declaration');
+     * ```
+     */
+    protected findNodes(ast: AST, nodeType: string): ASTNode[];
+    /**
+     * Find all nodes matching multiple types
+     *
+     * @param ast - The AST to search
+     * @param nodeTypes - Array of node types to find
+     * @returns Array of matching nodes
+     *
+     * @example
+     * ```typescript
+     * const declarations = this.findNodesByTypes(ast, ['function_declaration', 'arrow_function']);
+     * ```
+     */
+    protected findNodesByTypes(ast: AST, nodeTypes: string[]): ASTNode[];
+    /**
+     * Find the first node of a specific type
+     *
+     * @param ast - The AST to search
+     * @param nodeType - The type of node to find
+     * @returns The first matching node, or null if not found
+     */
+    protected findFirstNode(ast: AST, nodeType: string): ASTNode | null;
+    /**
+     * Find nodes matching a predicate function
+     *
+     * @param ast - The AST to search
+     * @param predicate - Function that returns true for matching nodes
+     * @returns Array of matching nodes
+     *
+     * @example
+     * ```typescript
+     * const asyncFunctions = this.findNodesWhere(ast, (node) =>
+     *   node.type === 'function_declaration' && node.text.includes('async')
+     * );
+     * ```
+     */
+    protected findNodesWhere(ast: AST, predicate: (node: ASTNode) => boolean): ASTNode[];
+    /**
+     * Find the nearest ancestor of a specific type
+     *
+     * Traverses up the tree from the given node to find the first ancestor
+     * matching the specified type.
+     *
+     * @param node - The starting node
+     * @param nodeType - The type of ancestor to find
+     * @param ast - The AST containing the node (needed for parent lookup)
+     * @returns The ancestor node, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const parentClass = this.findAncestor(methodNode, 'class_declaration', ast);
+     * ```
+     */
+    protected findAncestor(node: ASTNode, nodeType: string, ast: AST): ASTNode | null;
+    /**
+     * Find all ancestors of a node
+     *
+     * @param node - The starting node
+     * @param ast - The AST containing the node
+     * @returns Array of ancestor nodes from immediate parent to root
+     */
+    protected findAllAncestors(node: ASTNode, ast: AST): ASTNode[];
+    /**
+     * Find all descendants of a node
+     *
+     * @param node - The starting node
+     * @returns Array of all descendant nodes
+     */
+    protected findDescendants(node: ASTNode): ASTNode[];
+    /**
+     * Find descendants of a specific type
+     *
+     * @param node - The starting node
+     * @param nodeType - The type of descendants to find
+     * @returns Array of matching descendant nodes
+     */
+    protected findDescendantsByType(node: ASTNode, nodeType: string): ASTNode[];
+    /**
+     * Get the text content of a node
+     *
+     * Returns the source text corresponding to the node's position.
+     * If content is provided, extracts from content; otherwise uses node.text.
+     *
+     * @param node - The node to get text for
+     * @param content - Optional source content to extract from
+     * @returns The text content of the node
+     *
+     * @example
+     * ```typescript
+     * const functionName = this.getNodeText(identifierNode, context.content);
+     * ```
+     */
+    protected getNodeText(node: ASTNode, content?: string): string;
+    /**
+     * Get the trimmed text content of a node
+     *
+     * @param node - The node to get text for
+     * @param content - Optional source content to extract from
+     * @returns The trimmed text content
+     */
+    protected getNodeTextTrimmed(node: ASTNode, content?: string): string;
+    /**
+     * Match an AST against a pattern
+     *
+     * Searches the AST for nodes matching the specified pattern and returns
+     * all matches with their confidence scores.
+     *
+     * @param ast - The AST to search
+     * @param pattern - The pattern to match
+     * @returns Array of match results
+     *
+     * @example
+     * ```typescript
+     * const matches = this.matchPattern(ast, {
+     *   type: 'function_declaration',
+     *   children: [{ type: 'identifier', capture: 'name' }]
+     * });
+     * ```
+     */
+    protected matchPattern(ast: AST, pattern: ASTPattern): ASTMatchResult[];
+    /**
+     * Match a single node against a pattern
+     *
+     * @param node - The node to match
+     * @param pattern - The pattern to match against
+     * @param captures - Map to store captured nodes
+     * @returns Confidence score (0-1), 0 if no match
+     */
+    private matchNode;
+    /**
+     * Match text against a pattern (string or regex)
+     */
+    private matchText;
+    /**
+     * Match child patterns against node children
+     */
+    private matchChildPatterns;
+    /**
+     * Traverse the AST depth-first
+     *
+     * Visits each node in the AST, calling the visitor function.
+     * The visitor can return false to stop traversal of a subtree.
+     *
+     * @param ast - The AST to traverse
+     * @param visitor - Function called for each node
+     * @param options - Traversal options
+     *
+     * @example
+     * ```typescript
+     * this.traverse(ast, (node, parent, depth) => {
+     *   console.log(`${node.type} at depth ${depth}`);
+     *   if (depth > 5) return false; // Stop going deeper
+     * });
+     * ```
+     */
+    protected traverse(ast: AST, visitor: ASTVisitor, options?: TraversalOptions): void;
+    /**
+     * Traverse a specific node and its descendants
+     *
+     * @param node - The node to start traversal from
+     * @param visitor - Function called for each node
+     * @param options - Traversal options
+     */
+    protected traverseNode(node: ASTNode, visitor: ASTVisitor, options?: TraversalOptions): void;
+    /**
+     * Get the parent chain from root to a specific node
+     *
+     * @param ast - The AST to search
+     * @param targetNode - The node to find parents for
+     * @returns Array of parent nodes from root to immediate parent
+     */
+    protected getParentChain(ast: AST, targetNode: ASTNode): ASTNode[];
+    /**
+     * Get the immediate parent of a node
+     *
+     * @param ast - The AST containing the node
+     * @param node - The node to find the parent of
+     * @returns The parent node, or null if node is root
+     */
+    protected getParent(ast: AST, node: ASTNode): ASTNode | null;
+    /**
+     * Get the depth of a node in the AST
+     *
+     * @param ast - The AST containing the node
+     * @param targetNode - The node to get depth for
+     * @returns The depth (0 for root), or -1 if not found
+     */
+    protected getNodeDepth(ast: AST, targetNode: ASTNode): number;
+    /**
+     * Check if a node is a leaf node (has no children)
+     *
+     * @param node - The node to check
+     * @returns true if the node has no children
+     */
+    protected isLeafNode(node: ASTNode): boolean;
+    /**
+     * Get direct children of a specific type
+     *
+     * @param node - The parent node
+     * @param nodeType - The type of children to find
+     * @returns Array of matching child nodes
+     */
+    protected getChildrenByType(node: ASTNode, nodeType: string): ASTNode[];
+    /**
+     * Get the first direct child of a specific type
+     *
+     * @param node - The parent node
+     * @param nodeType - The type of child to find
+     * @returns The first matching child, or null if not found
+     */
+    protected getFirstChildByType(node: ASTNode, nodeType: string): ASTNode | null;
+    /**
+     * Check if a node has a child of a specific type
+     *
+     * @param node - The parent node
+     * @param nodeType - The type to check for
+     * @returns true if a child of the specified type exists
+     */
+    protected hasChildOfType(node: ASTNode, nodeType: string): boolean;
+    /**
+     * Check if a node has a descendant of a specific type
+     *
+     * @param node - The starting node
+     * @param nodeType - The type to check for
+     * @returns true if a descendant of the specified type exists
+     */
+    protected hasDescendantOfType(node: ASTNode, nodeType: string): boolean;
+    /**
+     * Get siblings of a node (other children of the same parent)
+     *
+     * @param ast - The AST containing the node
+     * @param node - The node to find siblings for
+     * @returns Array of sibling nodes (excluding the node itself)
+     */
+    protected getSiblings(ast: AST, node: ASTNode): ASTNode[];
+    /**
+     * Get the next sibling of a node
+     *
+     * @param ast - The AST containing the node
+     * @param node - The node to find the next sibling for
+     * @returns The next sibling, or null if none exists
+     */
+    protected getNextSibling(ast: AST, node: ASTNode): ASTNode | null;
+    /**
+     * Get the previous sibling of a node
+     *
+     * @param ast - The AST containing the node
+     * @param node - The node to find the previous sibling for
+     * @returns The previous sibling, or null if none exists
+     */
+    protected getPreviousSibling(ast: AST, node: ASTNode): ASTNode | null;
+    /**
+     * Count nodes of a specific type in the AST
+     *
+     * @param ast - The AST to search
+     * @param nodeType - The type of nodes to count
+     * @returns The count of matching nodes
+     */
+    protected countNodes(ast: AST, nodeType: string): number;
+    /**
+     * Check if the AST contains a node of a specific type
+     *
+     * @param ast - The AST to search
+     * @param nodeType - The type to check for
+     * @returns true if a node of the specified type exists
+     */
+    protected hasNodeOfType(ast: AST, nodeType: string): boolean;
+    /**
+     * Get the line number of a node (1-indexed)
+     *
+     * @param node - The node to get the line number for
+     * @returns The line number (1-indexed)
+     */
+    protected getLineNumber(node: ASTNode): number;
+    /**
+     * Get the column number of a node (1-indexed)
+     *
+     * @param node - The node to get the column number for
+     * @returns The column number (1-indexed)
+     */
+    protected getColumnNumber(node: ASTNode): number;
+}
+/**
+ * Type guard to check if a detector is an AST detector
+ *
+ * @param detector - The detector to check
+ * @returns true if the detector is an ASTDetector
+ */
+export declare function isASTDetector(detector: BaseDetector): detector is ASTDetector;
+//# sourceMappingURL=ast-detector.d.ts.map

package/dist/base/ast-detector.d.ts.map

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