@thinkingos/vsl-sdk 0.4.5 → 1.1.0

package/dist/index.d.ts

@@ -1,24 +1,39 @@
 /**
- * DOM extraction (T1.1.2, ROADMAP.md M1.1).
+ * Unified ID Generator for VSL (M1.7 optimization).
  *
- * Обходит дерево от корня (по умолчанию document.body) и извлекает все видимые
- * элементы с координатами (getBoundingClientRect), собственным текстом, атрибутами и CSS-подмножеством (Level 3, T1.5.1).
- * Покрывает тот же набор элементов, что и root.querySelectorAll('*'), минус отфильтрованные.
+ * Strategy:
+ *  1. Priority: use existing DOM `id` if present (stable, readable)
+ *  2. Fallback: short generated IDs with abbreviated types (btn_1, inp_2, cont_3)
  *
- * Фильтр невидимых (семантика ARCHITECTURE.md; CSS-уровень 3 вне scope M1.1):
- *  - непрендеримые теги (script/style/link/meta/noscript/template/head/title/base) —
- *    никогда не отрисовываются → пропуск поддерева;
- *  - display: none → элемент и всё поддерево не отрисованы → пропуск поддерева;
- *  - visibility: hidden → сам элемент невидим, но дети могут быть видимы
- *    (visibility: visible) → элемент не включается, поддерево обходится;
- *  - нулевой прямоугольник (width <= 0 || height <= 0) → нет видимого бокса, но дети
- *    (например, overflow) могут быть видимы → элемент не включается, поддерево обходится.
- *
- * indexPath — индексы среди ЭЛЕМЕНТНЫХ детей на каждом уровне, вычисляются по
- * структуре DOM ДО фильтрации: позиция стабильна независимо от фильтров — основа
- * детерминированных ID VSL (решение note_1789916091535: без Date.now()/Math.random(),
- * база для diffing в M1.2).
+ * Works for both browser path (SegmentedElement) and HTTP path (cheerio elements).
+ * IDs are deterministic (DOM traversal order is stable) and unique within a snapshot.
+ */
+/** Type abbreviations for short ID generation. */
+declare const TYPE_ABBREVIATIONS: Readonly<Record<string, string>>;
+/**
+ * ID Generator class for a single snapshot.
+ * Maintains a global counter to ensure uniqueness across the entire snapshot.
+ */
+declare class IdGenerator {
+    private typeCounters;
+    /**
+     * Generate ID for an element.
+     *
+     * @param elementId - Existing DOM id attribute (if present)
+     * @param vslType - VSL type of the element (for fallback abbreviation)
+     * @returns Generated ID string
+     */
+    generate(elementId: string | null | undefined, vslType: string | null): string;
+    /** Reset counters (for testing or new snapshot). */
+    reset(): void;
+    /** Get current counter value for a type (for debugging). */
+    getCounter(type?: string): number;
+}
+/**
+ * Create a new ID generator for a snapshot.
  */
+declare function createIdGenerator(): IdGenerator;
+
 interface Rect {
     x: number;
     y: number;
@@ -78,8 +93,11 @@ declare function ownText(el: Element): string;
 /**
  * Извлекает видимое поддерево DOM, начиная с root (по умолчанию document.body).
  * Сам root не включается — возвращается лес его видимых потомков.
+ *
+ * @param root — корневой элемент для обхода (по умолчанию document.body)
+ * @param url — URL страницы (для Prompt Injection Filter whitelist, T1.8.5)
  */
-declare function extractDomTree(root?: Element): ExtractedElement[];
+declare function extractDomTree(root?: Element, url?: string): ExtractedElement[];
 
 /**
  * Типы VSL JSON (DESIGN_SYSTEM.md §4, ARCHITECTURE.md §2.3).
@@ -1099,7 +1117,7 @@ declare const ACTION_TOOL_SCHEMA: {
         action: {
             type: string;
             description: string;
-            enum: ("select" | "type" | "click" | "expand" | "collapse" | "close" | "check" | "uncheck" | "clear" | "scroll" | "hover" | "focus" | "blur" | "drag" | "drop" | "submit" | "reset" | "open" | "wait" | "navigate" | "go_back" | "go_forward" | "refresh" | "download")[];
+            enum: ("select" | "scroll" | "type" | "click" | "expand" | "collapse" | "close" | "check" | "uncheck" | "clear" | "hover" | "focus" | "blur" | "drag" | "drop" | "submit" | "reset" | "open" | "wait" | "navigate" | "go_back" | "go_forward" | "refresh" | "download")[];
         };
         target_id: {
             type: string;
@@ -1311,6 +1329,349 @@ declare function executeAction(action: LlmAction, options?: ExecutorOptions): Pr
  */
 declare function resolveTarget(targetId: string, options?: ExecutorOptions): Element;
 
+/**
+ * Remote Patterns Loader (T1.8.3, M1.8, DEC-027).
+ *
+ * Загружает паттерны инъекций с удалённого CDN/GitHub, кэширует локально,
+ * обеспечивает fallback на bundled patterns при отсутствии интернета.
+ *
+ * Архитектура:
+ *  - Fetch: загрузка с remote URL (https://vsl.dev/patterns/latest.json)
+ *  - Cache: локальное кэширование (~/.vsl/cache/remote-patterns.json)
+ *  - Fallback: если fetch не удался, используем кэш или bundled patterns
+ *  - TTL: кэш валиден 24 часа (настраивается)
+ */
+
+/** Опции remote patterns loader. */
+interface RemotePatternsLoaderOptions {
+    /** URL для загрузки remote patterns. */
+    remoteUrl?: string;
+    /** Путь к локальному кэшу remote patterns. */
+    cachePath?: string;
+    /** TTL кэша в миллисекундах (по умолчанию 24 часа). */
+    cacheTtlMs?: number;
+    /** Включить/выключить remote loader (по умолчанию true). */
+    enabled?: boolean;
+    /** Timeout для HTTP-запроса в миллисекундах (по умолчанию 5000). */
+    timeoutMs?: number;
+}
+/** Результат загрузки remote patterns. */
+interface RemotePatternsResult {
+    /** Загруженные паттерны. */
+    patterns: InjectionPattern[];
+    /** Источник паттернов: 'remote' (свежая загрузка), 'cache' (из кэша), 'none' (нет паттернов). */
+    source: 'remote' | 'cache' | 'none';
+    /** Был ли использован fallback (если remote fetch не удался). */
+    fallbackUsed: boolean;
+    /** Ошибка (если произошла). */
+    error?: string;
+}
+/**
+ * Remote Patterns Loader — загрузка паттернов с CDN/GitHub.
+ *
+ * Использование:
+ *  * const loader = new RemotePatternsLoader({
+ *   remoteUrl: 'https://vsl.dev/patterns/latest.json',
+ *   cacheTtlMs: 24 * 60 * 60 * 1000, // 24 часа
+ * });
+ *
+ * const result = await loader.load();
+ * console.log(result.patterns); // Загруженные паттерны
+ * console.log(result.source); // 'remote' | 'cache' | 'none'
+ *  */
+declare class RemotePatternsLoader {
+    private remoteUrl;
+    private cachePath;
+    private cacheTtlMs;
+    private enabled;
+    private timeoutMs;
+    constructor(options?: RemotePatternsLoaderOptions);
+    /**
+     * Загружает remote patterns с fallback на кэш.
+     *
+     * Логика:
+     *  1. Если enabled === false — возвращаем empty
+     *  2. Проверяем кэш — если валиден (TTL не истёк), используем кэш
+     *  3. Пытаемся загрузить с remote URL
+     *  4. Если загрузка успешна — обновляем кэш, возвращаем remote patterns
+     *  5. Если загрузка не удалась — используем кэш (fallback)
+     *  6. Если кэша нет — возвращаем empty
+     */
+    load(): Promise<RemotePatternsResult>;
+    /**
+     * Загружает паттерны с remote URL.
+     */
+    private fetchRemotePatterns;
+    /**
+     * Проверяет валидность паттерна.
+     */
+    private isValidPattern;
+    /**
+     * Читает кэш из файла.
+     */
+    private readCache;
+    /**
+     * Записывает паттерны в кэш.
+     */
+    private writeCache;
+    /**
+     * Проверяет валидность кэша (TTL не истёк).
+     */
+    private isCacheValid;
+    /**
+     * Очищает кэш (для тестирования).
+     */
+    clearCache(): void;
+    /**
+     * Получает информацию о кэше (для диагностики).
+     */
+    getCacheInfo(): {
+        exists: boolean;
+        lastFetched?: string;
+        patternCount?: number;
+    };
+    /**
+     * Получает URL для загрузки remote patterns.
+     */
+    getRemoteUrl(): string;
+    /**
+     * Устанавливает URL для загрузки remote patterns.
+     */
+    setRemoteUrl(url: string): void;
+}
+
+/**
+ * Prompt Injection Filter (T1.8.1, M1.8, DEC-027).
+ *
+ * Слой безопасности на входе Capture Layer — сразу после извлечения текста из любого источника
+ * (DOM, raw HTML), до сегментации и упаковки в VSL JSON.
+ *
+ * Архитектура:
+ *  - Scanner — regex-паттерны для обнаружения инъекций
+ *  - Logger — security audit trail (локальное хранение)
+ *  - Stripper — вырезание инъекций из текста
+ *
+ * 3 уровня паттернов:
+ *  - Bundled (patterns_v1.json в SDK)
+ *  - Remote (CDN/GitHub, автозагрузка при запуске)
+ *  - Custom (пользовательские через vsl.config.json)
+ *
+ * Действия:
+ *  - strip — вырезать инъекцию, оставить остальной контент
+ *  - log — только логировать обнаружение
+ *  - block — блокировать весь текст (вернуть пустую строку)
+ *
+ * False positive strategy:
+ *  - Confidence threshold (0.7 по умолчанию)
+ *  - Domain whitelist (доверенные домены пропускаются)
+ *  - User override (отключение фильтра для конкретных доменов)
+ */
+
+/** Тип паттерна (пока только regex, ML зарезервирован). */
+type PatternType = 'regex' | 'ml';
+/** Уровень серьёзности инъекции. */
+type Severity = 'low' | 'medium' | 'high' | 'critical';
+/** Действие при обнаружении инъекции. */
+type FilterAction = 'strip' | 'log' | 'block';
+/** Формат паттерна для обнаружения инъекций. */
+interface InjectionPattern {
+    /** Уникальный идентификатор паттерна. */
+    id: string;
+    /** Regex-паттерн для обнаружения инъекции. */
+    pattern: string;
+    /** Тип паттерна (regex или ml). */
+    type: PatternType;
+    /** Уровень серьёзности. */
+    severity: Severity;
+    /** Действие при обнаружении. */
+    action: FilterAction;
+    /** Описание паттерна. */
+    description: string;
+    /** Confidence threshold (0-1), по умолчанию 0.7. */
+    confidence?: number;
+}
+/** Результат сканирования текста. */
+interface ScanResult {
+    /** Очищенный текст (после strip/block). */
+    cleanText: string;
+    /** Обнаруженные инъекции. */
+    detections: Detection[];
+    /** Был ли текст заблокирован полностью. */
+    blocked: boolean;
+    /** Время сканирования (мс). */
+    scanTimeMs: number;
+}
+/** Обнаруженная инъекция. */
+interface Detection {
+    /** ID паттерна, который сработал. */
+    patternId: string;
+    /** Описание паттерна. */
+    description: string;
+    /** Уровень серьёзности. */
+    severity: Severity;
+    /** Действие, которое было выполнено. */
+    action: FilterAction;
+    /** Текст, который совпал с паттерном. */
+    matchedText: string;
+    /** Позиция в исходном тексте (start index). */
+    index: number;
+    /** Контекст вокруг совпадения (для аудита). */
+    context: string;
+}
+/** Запись в security audit log. */
+interface SecurityLogEntry {
+    /** Timestamp обнаружения (ISO 8601). */
+    timestamp: string;
+    /** URL страницы (если доступен). */
+    url?: string;
+    /** ID паттерна. */
+    patternId: string;
+    /** Описание паттерна. */
+    description: string;
+    /** Уровень серьёзности. */
+    severity: Severity;
+    /** Действие, которое было выполнено. */
+    action: FilterAction;
+    /** Текст, который совпал с паттерном. */
+    matchedText: string;
+    /** Контекст вокруг совпадения. */
+    context: string;
+}
+/** Опции конфигурации фильтра. */
+interface FilterOptions {
+    /** Включить/выключить фильтр (по умолчанию true). */
+    enabled?: boolean;
+    /** Confidence threshold (0-1, по умолчанию 0.7). */
+    confidenceThreshold?: number;
+    /** Domain whitelist — доверенные домены, которые пропускаются. */
+    domainWhitelist?: string[];
+    /** Путь к bundled patterns.json. */
+    bundledPatternsPath?: string;
+    /** Путь к remote patterns (локальный кэш). */
+    remotePatternsPath?: string;
+    /** Custom patterns (из vsl.config.json). */
+    customPatterns?: InjectionPattern[];
+    /** Путь к security audit log. */
+    logPath?: string;
+    /** Максимальный размер лога (количество записей, по умолчанию 10000). */
+    maxLogEntries?: number;
+    /** Опции для RemotePatternsLoader (автозагрузка с CDN). */
+    remoteLoader?: RemotePatternsLoaderOptions;
+}
+/**
+ * Prompt Injection Filter — основной класс фильтра.
+ *
+ * Использование:
+ *  * const filter = new PromptInjectionFilter({
+ *   enabled: true,
+ *   confidenceThreshold: 0.7,
+ *   domainWhitelist: ['github.com', 'docs.google.com'],
+ * });
+ *
+ * const result = filter.scan(text, 'https://example.com');
+ * console.log(result.cleanText); // Очищенный текст
+ * console.log(result.detections); // Обнаруженные инъекции
+ *  */
+declare class PromptInjectionFilter {
+    private enabled;
+    private confidenceThreshold;
+    private domainWhitelist;
+    private patterns;
+    private logPath;
+    private maxLogEntries;
+    private logEntries;
+    private remoteLoader;
+    constructor(options?: FilterOptions);
+    /**
+     * Загружает паттерны из всех источников (bundled, remote, custom).
+     */
+    private loadPatterns;
+    /**
+     * Асинхронно загружает remote patterns через RemotePatternsLoader.
+     * Вызывается опционально для обновления паттернов с CDN/GitHub.
+     *
+     * @returns Результат загрузки remote patterns
+     */
+    loadRemotePatterns(): Promise<{
+        patterns: number;
+        source: string;
+        fallbackUsed: boolean;
+        error?: string;
+    }>;
+    /**
+     * Получает информацию о кэше remote patterns.
+     */
+    getRemoteCacheInfo(): {
+        exists: boolean;
+        lastFetched?: string;
+        patternCount?: number;
+    };
+    /**
+     * Очищает кэш remote patterns.
+     */
+    clearRemoteCache(): void;
+    /**
+     * Загружает существующие логи из файла.
+     */
+    private loadExistingLogs;
+    /**
+     * Проверяет, находится ли URL в whitelist.
+     */
+    isWhitelisted(url?: string): boolean;
+    /**
+     * Сканирует текст на наличие инъекций.
+     *
+     * @param text — текст для сканирования
+     * @param url — URL страницы (для whitelist и логирования)
+     * @returns Результат сканирования с очищенным текстом и списком обнаружений
+     */
+    scan(text: string, url?: string): ScanResult;
+    /**
+     * Логирует обнаружение в security audit trail.
+     */
+    private logDetection;
+    /**
+     * Записывает одну запись в лог-файл.
+     */
+    private writeLogEntry;
+    /**
+     * Получает все логи (для аудита).
+     */
+    getLogs(): SecurityLogEntry[];
+    /**
+     * Очищает логи (для тестирования).
+     */
+    clearLogs(): void;
+    /**
+     * Добавляет custom pattern динамически.
+     */
+    addCustomPattern(pattern: InjectionPattern): void;
+    /**
+     * Удаляет custom pattern по ID.
+     */
+    removePattern(patternId: string): boolean;
+    /**
+     * Получает количество загруженных паттернов.
+     */
+    getPatternCount(): number;
+    /**
+     * Включает/выключает фильтр.
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Проверяет, включён ли фильтр.
+     */
+    isEnabled(): boolean;
+}
+/**
+ * Фабричная функция для создания фильтра с дефолтными настройками.
+ */
+declare function createFilter(options?: FilterOptions): PromptInjectionFilter;
+/**
+ * Получает глобальный экземпляр фильтра.
+ */
+declare function getGlobalFilter(): PromptInjectionFilter;
+
 /**
  * VSL SDK — публичное API. Точка входа:
  *  - Snapshot generation (M1.1): capture → segment → build;
@@ -1321,4 +1682,4 @@ declare function resolveTarget(targetId: string, options?: ExecutorOptions): Ele
 
 declare const VSL_SDK_VERSION = "0.1.0";
 
-export { ACTION_TOOL_DESCRIPTION, ACTION_TOOL_NAME, ACTION_TOOL_SCHEMA, ARIA_ROLE_TYPE_MAP, ActionExecutionError, type ActionResult, AlibabaAdapter, AnthropicAdapter, type BuildOptions, type CacheEntry, type CacheStore, type DecideInput, type DiffOptions, type ExecutorOptions, type ExtractedElement, type FewShotExample, LEVEL1_TAG_MAP, type LlmAction, type LlmAdapter, type LlmAdapterConfig, LlmError, type LlmResponse, type LlmTransport, type LlmUsage, LlmValidationError, type MutationObserverHandle, OpenAIAdapter, type Rect, type RetryOptions, type SegmentedElement, type SendPromptOptions, type Sleep, type SnapshotInput, type SnapshotResult, VALID_ACTIONS, VSL_SDK_VERSION, VSL_VERSION, type ValidAction, type VisualFragment, type VisualFragmentData, type VisualFragmentStore, type VisualFragmentType, type VslCanvas, type VslDiff, type VslDiffChanges, type VslDocument, type VslFragmentMeta, type VslInput, type VslModifiedObject, type VslObject, type VslObjectWithVf, type VslRemovedObject, VslSnapshotSession, type VslState, type VslType, type VslViewport, attachMutationObserver, buildSystemPrompt, buildUserPrompt, buildVslDocument, collectIds, computeContentHash, computeCoordHash, createCacheStore, diffVslDocuments, executeAction, extractDomTree, isAriaHidden, isVslDiff, ownText, resolveAriaRoleType, resolveLevel1Type, resolveSt, resolveTarget, retryWithBackoff, segmentTree, validateAction };
+export { ACTION_TOOL_DESCRIPTION, ACTION_TOOL_NAME, ACTION_TOOL_SCHEMA, ARIA_ROLE_TYPE_MAP, ActionExecutionError, type ActionResult, AlibabaAdapter, AnthropicAdapter, type BuildOptions, type CacheEntry, type CacheStore, type DecideInput, type Detection, type DiffOptions, type ExecutorOptions, type ExtractedElement, type FewShotExample, type FilterAction, type FilterOptions, IdGenerator, type InjectionPattern, LEVEL1_TAG_MAP, type LlmAction, type LlmAdapter, type LlmAdapterConfig, LlmError, type LlmResponse, type LlmTransport, type LlmUsage, LlmValidationError, type MutationObserverHandle, OpenAIAdapter, type PatternType, PromptInjectionFilter, type Rect, RemotePatternsLoader, type RemotePatternsLoaderOptions, type RemotePatternsResult, type RetryOptions, type ScanResult, type SecurityLogEntry, type SegmentedElement, type SendPromptOptions, type Severity, type Sleep, type SnapshotInput, type SnapshotResult, TYPE_ABBREVIATIONS, VALID_ACTIONS, VSL_SDK_VERSION, VSL_VERSION, type ValidAction, type VisualFragment, type VisualFragmentData, type VisualFragmentStore, type VisualFragmentType, type VslCanvas, type VslDiff, type VslDiffChanges, type VslDocument, type VslFragmentMeta, type VslInput, type VslModifiedObject, type VslObject, type VslObjectWithVf, type VslRemovedObject, VslSnapshotSession, type VslState, type VslType, type VslViewport, attachMutationObserver, buildSystemPrompt, buildUserPrompt, buildVslDocument, collectIds, computeContentHash, computeCoordHash, createCacheStore, createFilter, createIdGenerator, diffVslDocuments, executeAction, extractDomTree, getGlobalFilter, isAriaHidden, isVslDiff, ownText, resolveAriaRoleType, resolveLevel1Type, resolveSt, resolveTarget, retryWithBackoff, segmentTree, validateAction };