/**
 * EntitlementScanner — Hardened Multi-Layer Blast Radius Analysis
 *
 * **Evolution 5: Blast Radius**
 *
 * Performs static analysis of handler source files to detect
 * I/O capabilities (filesystem, network, subprocess, crypto,
 * code evaluation) that expand the tool's blast radius beyond
 * what its declarative contract suggests.
 *
 * **Key insight**: A tool declared as `readOnly: true` that
 * imports `child_process` has a mismatch between its declared
 * contract and its actual capabilities. This scanner detects
 * such mismatches and reports them as entitlement violations.
 *
 * **Multi-layer defense**:
 *
 * 1. **Pattern detection** — Regex-based pattern matching for
 *    known I/O APIs across 5 categories. Conservative: may
 *    over-report but never under-report.
 *
 * 2. **Code evaluation detection** — Detects `eval()`,
 *    `new Function()`, `vm` module, indirect eval, and other
 *    dynamic code execution vectors.
 *
 * 3. **Evasion heuristics** — Detects techniques commonly used
 *    to bypass static analysis: `String.fromCharCode()`,
 *    bracket-notation global access, computed require/import,
 *    high encoding density, and entropy anomalies in string
 *    literals.
 *
 * The evasion layer does NOT try to determine what obfuscated
 * code does — it flags the *presence of obfuscation itself*
 * as a security concern. Code that hides its intent is
 * inherently untrustworthy.
 *
 * **Contract integration**: The entitlement report is embedded
 * in the `ToolContract.entitlements` field, making entitlement
 * changes trackable via `ContractDiff`.
 *
 * Pure-function module: no state, no side effects.
 *
 * @module
 */
import type { HandlerEntitlements } from './ToolContract.js';
/**
 * Complete entitlement report for a handler.
 */
export interface EntitlementReport {
    /** Resolved entitlements */
    readonly entitlements: HandlerEntitlements;
    /** All detected entitlement matches */
    readonly matches: readonly EntitlementMatch[];
    /** Entitlement violations (declared vs detected mismatches) */
    readonly violations: readonly EntitlementViolation[];
    /** Evasion indicators — patterns suggesting intentional detection bypass */
    readonly evasionIndicators: readonly EvasionIndicator[];
    /** Whether the handler is considered safe */
    readonly safe: boolean;
    /** Human-readable summary */
    readonly summary: string;
}
/**
 * A single entitlement match detected in source code.
 */
export interface EntitlementMatch {
    /** Which entitlement category */
    readonly category: EntitlementCategory;
    /** The specific API/import detected */
    readonly identifier: string;
    /** Pattern that matched */
    readonly pattern: string;
    /** Source text (context around the match) */
    readonly context: string;
    /** Line number in the source (1-based) */
    readonly line: number;
}
/**
 * An entitlement violation — mismatch between declaration and detection.
 */
export interface EntitlementViolation {
    /** Which entitlement is violated */
    readonly category: EntitlementCategory;
    /** What was declared (e.g., readOnly: true) */
    readonly declared: string;
    /** What was detected */
    readonly detected: string;
    /** Severity */
    readonly severity: 'warning' | 'error';
    /** Human-readable description */
    readonly description: string;
}
/** Entitlement categories */
export type EntitlementCategory = 'filesystem' | 'network' | 'subprocess' | 'crypto' | 'codeEvaluation';
/**
 * Declaration claims for validation against detected entitlements.
 */
export interface EntitlementClaims {
    /** Whether the action is declared as readOnly */
    readonly readOnly?: boolean;
    /** Whether the action is declared as destructive */
    readonly destructive?: boolean;
    /** Explicitly allowed entitlements (bypasses violation detection) */
    readonly allowed?: readonly EntitlementCategory[];
}
/**
 * Evasion indicator — suspicious pattern suggesting intentional
 * static-analysis bypass.
 *
 * Evasion indicators do NOT identify a specific I/O capability.
 * Instead, they flag *techniques* commonly used to hide intent:
 * string construction, bracket-notation access, computed imports,
 * high-entropy payloads, and dense hex/unicode escape sequences.
 */
export interface EvasionIndicator {
    /** Type of evasion technique detected */
    readonly type: EvasionType;
    /** Confidence level — high confidence makes handler UNSAFE */
    readonly confidence: 'low' | 'medium' | 'high';
    /** Human-readable description */
    readonly description: string;
    /** Source context around the match */
    readonly context: string;
    /** Line number (1-based) */
    readonly line: number;
}
/** Evasion technique categories */
export type EvasionType = 'string-construction' | 'indirect-access' | 'computed-import' | 'encoding-density' | 'entropy-anomaly';
/**
 * Scan source text for entitlement patterns.
 *
 * @param source - The source code text to scan
 * @param fileName - File name for reporting (optional)
 * @returns All entitlement matches found
 */
export declare function scanSource(source: string, fileName?: string): readonly EntitlementMatch[];
/**
 * Scan source for evasion indicators.
 *
 * This is a secondary analysis pass that detects patterns
 * commonly associated with intentional static-analysis bypass.
 * Unlike `scanSource`, which identifies specific I/O capabilities,
 * this function flags *evasion techniques* regardless of what
 * they ultimately execute.
 *
 * @param source - Source code text
 * @returns Detected evasion indicators
 */
export declare function scanEvasionIndicators(source: string): readonly EvasionIndicator[];
/**
 * Build `HandlerEntitlements` from detected matches.
 *
 * @param matches - Detected entitlement matches
 * @returns Aggregated entitlements
 */
export declare function buildEntitlements(matches: readonly EntitlementMatch[]): HandlerEntitlements;
/**
 * Validate detected entitlements against declared claims.
 *
 * Uses a rule table instead of imperative branching.
 * Each rule encodes a policy check as pure data.
 *
 * @param matches - Detected matches
 * @param claims - Declared claims from action metadata
 * @returns Violations found
 */
export declare function validateClaims(matches: readonly EntitlementMatch[], claims: EntitlementClaims): readonly EntitlementViolation[];
/**
 * Perform a complete entitlement scan and validation.
 *
 * @param source - Handler source code
 * @param claims - Declared claims for validation
 * @param fileName - Optional file name for reporting
 * @returns Complete entitlement report
 */
export declare function scanAndValidate(source: string, claims?: EntitlementClaims, fileName?: string): EntitlementReport;
//# sourceMappingURL=EntitlementScanner.d.ts.map