@panguard-ai/atr 0.2.0

package/dist/rule-scaffolder.js

@@ -0,0 +1,173 @@
+/**
+ * ATR Rule Scaffolder - Generates ATR rule YAML scaffolds from structured input
+ * @module agent-threat-rules/rule-scaffolder
+ */
+import yaml from 'js-yaml';
+const CATEGORY_TO_SOURCE_TYPE = {
+    'prompt-injection': 'llm_io',
+    'tool-poisoning': 'tool_call',
+    'context-exfiltration': 'context_window',
+    'agent-manipulation': 'multi_agent_comm',
+    'privilege-escalation': 'agent_behavior',
+    'excessive-autonomy': 'agent_behavior',
+    'data-poisoning': 'llm_io',
+    'model-abuse': 'llm_io',
+    'skill-compromise': 'skill_lifecycle',
+};
+const CATEGORY_TO_FIELD = {
+    'prompt-injection': 'user_input',
+    'tool-poisoning': 'tool_response',
+    'context-exfiltration': 'agent_output',
+    'agent-manipulation': 'agent_message',
+    'privilege-escalation': 'agent_action',
+    'excessive-autonomy': 'agent_action',
+    'data-poisoning': 'training_input',
+    'model-abuse': 'user_input',
+    'skill-compromise': 'skill_manifest',
+};
+const SEVERITY_TO_ACTIONS = {
+    critical: ['block_input', 'alert', 'escalate'],
+    high: ['block_input', 'alert'],
+    medium: ['alert', 'snapshot'],
+    low: ['alert'],
+    informational: ['alert'],
+};
+const REGEX_SPECIAL_CHARS = /[.*+?^${}()|[\]\\]/g;
+function escapeRegex(str) {
+    return str.replace(REGEX_SPECIAL_CHARS, '\\$&');
+}
+/**
+ * Build a case-insensitive regex pattern from a payload string.
+ * Extracts significant keywords (length > 3) and creates lookahead assertions,
+ * falling back to a simple escaped match for short payloads.
+ */
+function buildRegexPattern(payload) {
+    const trimmed = payload.trim();
+    const words = trimmed.split(/\s+/).filter((w) => w.length > 3);
+    if (words.length === 0) {
+        return `(?i).*${escapeRegex(trimmed)}.*`;
+    }
+    const keywords = words.slice(0, 4);
+    return `(?i)${keywords.map((k) => `(?=.*${escapeRegex(k)})`).join('')}`;
+}
+function generateId() {
+    const year = new Date().getFullYear();
+    const seq = String(Math.floor(Math.random() * 900) + 100);
+    return `ATR-${year}-${seq}`;
+}
+function getCurrentDate() {
+    return new Date().toISOString().split('T')[0];
+}
+export class RuleScaffolder {
+    options;
+    constructor(options = {}) {
+        this.options = {
+            author: options.author ?? 'ATR Community (auto-scaffolded)',
+            schemaVersion: options.schemaVersion ?? '0.1',
+        };
+    }
+    /**
+     * Generate a complete ATR YAML rule from structured input.
+     * Returns a ScaffoldResult with the YAML string, generated ID, and any warnings.
+     */
+    scaffold(input) {
+        const warnings = this.validateInput(input);
+        const severity = input.severity ?? 'medium';
+        const sourceType = input.agentSourceType ?? CATEGORY_TO_SOURCE_TYPE[input.category];
+        const field = CATEGORY_TO_FIELD[input.category];
+        const id = generateId();
+        const date = getCurrentDate();
+        const conditions = input.examplePayloads.map((payload, idx) => ({
+            field,
+            operator: 'regex',
+            value: buildRegexPattern(payload),
+            description: `Pattern ${idx + 1}: detects "${payload.trim()}"`,
+        }));
+        const truePositives = input.examplePayloads.map((payload) => ({
+            input: payload.trim(),
+            expected: 'trigger',
+        }));
+        const trueNegatives = [
+            {
+                input: 'TODO: Add benign input that should not trigger this rule',
+                expected: 'no_trigger',
+            },
+        ];
+        const references = {};
+        if (input.owaspRefs && input.owaspRefs.length > 0) {
+            references.owasp_llm = [...input.owaspRefs];
+        }
+        if (input.mitreRefs && input.mitreRefs.length > 0) {
+            references.mitre_atlas = [...input.mitreRefs];
+        }
+        const conditionExpr = conditions.length > 1 ? 'any' : 'all';
+        const rule = {
+            title: input.title,
+            id,
+            schema_version: this.options.schemaVersion,
+            status: 'draft',
+            description: input.attackDescription,
+            author: this.options.author,
+            date,
+            severity,
+            detection_tier: 'pattern',
+            maturity: 'draft',
+            ...(Object.keys(references).length > 0 ? { references } : {}),
+            tags: {
+                category: input.category,
+                confidence: severity === 'critical' || severity === 'high' ? 'high' : 'medium',
+            },
+            agent_source: {
+                type: sourceType,
+            },
+            detection: {
+                conditions,
+                condition: conditionExpr,
+                false_positives: [
+                    'TODO: Document known false positive scenarios',
+                ],
+            },
+            response: {
+                actions: [...SEVERITY_TO_ACTIONS[severity]],
+                message_template: `Potential ${input.category} detected: {{matched_patterns}}`,
+            },
+            test_cases: {
+                true_positives: truePositives,
+                true_negatives: trueNegatives,
+            },
+        };
+        const yamlStr = yaml.dump(rule, {
+            indent: 2,
+            lineWidth: 120,
+            noRefs: true,
+            sortKeys: false,
+            quotingType: '"',
+            forceQuotes: false,
+        });
+        return { yaml: yamlStr, id, warnings };
+    }
+    /**
+     * Validate scaffold input, throwing on invalid required fields
+     * and returning warnings for non-critical issues.
+     */
+    validateInput(input) {
+        const warnings = [];
+        if (!input.title || input.title.trim().length === 0) {
+            throw new Error('ScaffoldInput.title is required and must be non-empty');
+        }
+        if (!input.category) {
+            throw new Error('ScaffoldInput.category is required');
+        }
+        if (!input.attackDescription || input.attackDescription.trim().length === 0) {
+            throw new Error('ScaffoldInput.attackDescription is required and must be non-empty');
+        }
+        if (!input.examplePayloads || input.examplePayloads.length === 0) {
+            throw new Error('ScaffoldInput.examplePayloads must contain at least one payload');
+        }
+        if (input.examplePayloads.length < 3) {
+            warnings.push('Fewer than 3 example payloads - consider adding more for better pattern coverage.');
+        }
+        return warnings;
+    }
+}
+//# sourceMappingURL=rule-scaffolder.js.map

package/dist/rule-scaffolder.js.map

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

package/dist/session-tracker.d.ts

@@ -0,0 +1,56 @@
+/**
+ * SessionTracker - Tracks per-session state for behavioral detection operators.
+ *
+ * Enables multi-turn injection detection, call frequency tracking,
+ * and pattern repetition counting. All state is internal; public methods
+ * return copies to preserve immutability.
+ *
+ * @module agent-threat-rules/session-tracker
+ */
+import type { AgentEvent } from './types.js';
+/** Snapshot of session state returned to callers (immutable copy) */
+export interface SessionStateSnapshot {
+    readonly sessionId: string;
+    readonly eventCount: number;
+    readonly oldestEventTimestamp: number | undefined;
+    readonly newestEventTimestamp: number | undefined;
+}
+export declare class SessionTracker {
+    private readonly sessions;
+    /**
+     * Record an agent event for the given session.
+     * Extracts tool name and patterns from event fields/content.
+     */
+    recordEvent(sessionId: string, event: AgentEvent, patterns?: readonly string[]): void;
+    /**
+     * Get the number of calls to a specific tool within a time window.
+     */
+    getCallFrequency(sessionId: string, toolName: string, windowMs: number): number;
+    /**
+     * Get the number of times a pattern has been observed within a time window.
+     */
+    getPatternFrequency(sessionId: string, pattern: string, windowMs: number): number;
+    /**
+     * Get total event count for a session, optionally within a time window.
+     */
+    getEventCount(sessionId: string, windowMs?: number): number;
+    /**
+     * Get an immutable snapshot of session state. Returns undefined if session does not exist.
+     */
+    getSessionSnapshot(sessionId: string): SessionStateSnapshot | undefined;
+    /**
+     * Evict sessions that have been inactive longer than maxAgeMs.
+     * Returns the number of sessions evicted.
+     */
+    cleanup(maxAgeMs: number): number;
+    /** Get the number of tracked sessions */
+    getSessionCount(): number;
+    /**
+     * Ensure we don't exceed the maximum session count.
+     * Evicts the oldest session if at capacity.
+     */
+    private ensureCapacity;
+    private getOrCreateSession;
+    private extractToolName;
+}
+//# sourceMappingURL=session-tracker.d.ts.map

package/dist/session-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-tracker.d.ts","sourceRoot":"","sources":["../src/session-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAgB7C,qEAAqE;AACrE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAC;CACnD;AAWD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAE5D;;;OAGG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,GAAE,SAAS,MAAM,EAAO,GAAG,IAAI;IAkCzF;;OAEG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAc/E;;OAEG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAcjF;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM;IAkB3D;;OAEG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS;IAevE;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAcjC,yCAAyC;IACzC,eAAe,IAAI,MAAM;IAIzB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAkBtB,OAAO,CAAC,kBAAkB;IAgB1B,OAAO,CAAC,eAAe;CAMxB"}

package/dist/session-tracker.js

@@ -0,0 +1,175 @@
+/**
+ * SessionTracker - Tracks per-session state for behavioral detection operators.
+ *
+ * Enables multi-turn injection detection, call frequency tracking,
+ * and pattern repetition counting. All state is internal; public methods
+ * return copies to preserve immutability.
+ *
+ * @module agent-threat-rules/session-tracker
+ */
+/** Maximum number of events stored per session */
+const MAX_EVENTS_PER_SESSION = 1000;
+/** Maximum number of tracked sessions */
+const MAX_SESSIONS = 10_000;
+export class SessionTracker {
+    sessions = new Map();
+    /**
+     * Record an agent event for the given session.
+     * Extracts tool name and patterns from event fields/content.
+     */
+    recordEvent(sessionId, event, patterns = []) {
+        this.ensureCapacity();
+        const state = this.getOrCreateSession(sessionId);
+        const toolName = this.extractToolName(event);
+        const now = Date.now();
+        const tracked = {
+            event: Object.freeze({ ...event }),
+            recordedAt: now,
+            toolName,
+            patterns,
+        };
+        // Evict oldest if at capacity
+        if (state.events.length >= MAX_EVENTS_PER_SESSION) {
+            state.events = state.events.slice(1);
+        }
+        state.events = [...state.events, tracked];
+        state.lastActivityAt = now;
+        // Update call counts
+        if (toolName) {
+            const prev = state.callCounts.get(toolName) ?? 0;
+            state.callCounts.set(toolName, prev + 1);
+        }
+        // Update pattern counts
+        for (const p of patterns) {
+            const prev = state.patternCounts.get(p) ?? 0;
+            state.patternCounts.set(p, prev + 1);
+        }
+    }
+    /**
+     * Get the number of calls to a specific tool within a time window.
+     */
+    getCallFrequency(sessionId, toolName, windowMs) {
+        const state = this.sessions.get(sessionId);
+        if (!state)
+            return 0;
+        const cutoff = Date.now() - windowMs;
+        let count = 0;
+        for (const tracked of state.events) {
+            if (tracked.recordedAt >= cutoff && tracked.toolName === toolName) {
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Get the number of times a pattern has been observed within a time window.
+     */
+    getPatternFrequency(sessionId, pattern, windowMs) {
+        const state = this.sessions.get(sessionId);
+        if (!state)
+            return 0;
+        const cutoff = Date.now() - windowMs;
+        let count = 0;
+        for (const tracked of state.events) {
+            if (tracked.recordedAt >= cutoff && tracked.patterns.includes(pattern)) {
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Get total event count for a session, optionally within a time window.
+     */
+    getEventCount(sessionId, windowMs) {
+        const state = this.sessions.get(sessionId);
+        if (!state)
+            return 0;
+        if (windowMs === undefined) {
+            return state.events.length;
+        }
+        const cutoff = Date.now() - windowMs;
+        let count = 0;
+        for (const tracked of state.events) {
+            if (tracked.recordedAt >= cutoff) {
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Get an immutable snapshot of session state. Returns undefined if session does not exist.
+     */
+    getSessionSnapshot(sessionId) {
+        const state = this.sessions.get(sessionId);
+        if (!state)
+            return undefined;
+        const oldest = state.events.length > 0 ? state.events[0].recordedAt : undefined;
+        const newest = state.events.length > 0 ? state.events[state.events.length - 1].recordedAt : undefined;
+        return Object.freeze({
+            sessionId,
+            eventCount: state.events.length,
+            oldestEventTimestamp: oldest,
+            newestEventTimestamp: newest,
+        });
+    }
+    /**
+     * Evict sessions that have been inactive longer than maxAgeMs.
+     * Returns the number of sessions evicted.
+     */
+    cleanup(maxAgeMs) {
+        const cutoff = Date.now() - maxAgeMs;
+        let evicted = 0;
+        for (const [id, state] of this.sessions) {
+            if (state.lastActivityAt < cutoff) {
+                this.sessions.delete(id);
+                evicted++;
+            }
+        }
+        return evicted;
+    }
+    /** Get the number of tracked sessions */
+    getSessionCount() {
+        return this.sessions.size;
+    }
+    /**
+     * Ensure we don't exceed the maximum session count.
+     * Evicts the oldest session if at capacity.
+     */
+    ensureCapacity() {
+        if (this.sessions.size < MAX_SESSIONS)
+            return;
+        let oldestId;
+        let oldestTime = Infinity;
+        for (const [id, state] of this.sessions) {
+            if (state.lastActivityAt < oldestTime) {
+                oldestTime = state.lastActivityAt;
+                oldestId = id;
+            }
+        }
+        if (oldestId) {
+            this.sessions.delete(oldestId);
+        }
+    }
+    getOrCreateSession(sessionId) {
+        const existing = this.sessions.get(sessionId);
+        if (existing)
+            return existing;
+        const now = Date.now();
+        const state = {
+            events: [],
+            callCounts: new Map(),
+            patternCounts: new Map(),
+            createdAt: now,
+            lastActivityAt: now,
+        };
+        this.sessions.set(sessionId, state);
+        return state;
+    }
+    extractToolName(event) {
+        if (event.type === 'tool_call' || event.type === 'tool_response') {
+            return event.fields?.['tool_name'] ?? event.content;
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=session-tracker.js.map

package/dist/session-tracker.js.map

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

package/dist/skill-fingerprint.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Skill Behavioral Fingerprint
+ * Skill 行為指紋追蹤器
+ *
+ * Tracks what each skill "normally does" across invocations, then detects
+ * behavioral drift when a previously-trusted skill starts acting differently.
+ *
+ * Solves the "installed then turns malicious" scenario:
+ * - First N invocations: build fingerprint (what APIs, what patterns, what scope)
+ * - After fingerprint stabilizes: flag any deviation as anomaly
+ *
+ * 追蹤每個 skill 的「正常行為」，然後在行為偏移時偵測：
+ * - 前 N 次呼叫：建立指紋
+ * - 指紋穩定後：任何偏離都標記為異常
+ *
+ * @module agent-threat-rules/skill-fingerprint
+ */
+import type { AgentEvent } from './types.js';
+/** Behavioral capabilities observed for a skill */
+interface SkillCapabilities {
+    /** Seen filesystem operations (read/write/delete) */
+    readonly filesystemOps: ReadonlySet<string>;
+    /** Seen network destinations (hostnames) */
+    readonly networkTargets: ReadonlySet<string>;
+    /** Seen environment variable accesses */
+    readonly envAccesses: ReadonlySet<string>;
+    /** Seen child process executions */
+    readonly processExecs: ReadonlySet<string>;
+    /** Seen output patterns (categories: data, error, redirect, exfiltration) */
+    readonly outputPatterns: ReadonlySet<string>;
+}
+/** Immutable fingerprint snapshot */
+export interface SkillFingerprint {
+    readonly skillName: string;
+    readonly invocationCount: number;
+    readonly firstSeen: number;
+    readonly lastSeen: number;
+    readonly isStable: boolean;
+    readonly capabilities: SkillCapabilities;
+    /** Hash of capabilities for quick comparison */
+    readonly capabilityHash: string;
+}
+/** Anomaly when behavior deviates from fingerprint */
+export interface BehaviorAnomaly {
+    readonly skillName: string;
+    readonly anomalyType: 'new_filesystem_op' | 'new_network_target' | 'new_env_access' | 'new_process_exec' | 'new_output_pattern' | 'capability_expansion';
+    readonly description: string;
+    readonly severity: 'low' | 'medium' | 'high' | 'critical';
+    readonly newValue: string;
+    readonly timestamp: number;
+}
+export interface SkillFingerprintConfig {
+    /** Minimum invocations before fingerprint can stabilize (default: 10) */
+    stabilityThreshold?: number;
+    /** Consecutive clean invocations to mark stable (default: 5) */
+    stableStreak?: number;
+}
+export declare class SkillFingerprintStore {
+    private readonly fingerprints;
+    private readonly stabilityThreshold;
+    private readonly stableStreak;
+    constructor(config?: SkillFingerprintConfig);
+    /**
+     * Record a skill invocation and detect behavioral anomalies.
+     * Returns anomalies if the fingerprint was stable and new capabilities appeared.
+     *
+     * 記錄 skill 呼叫並偵測行為異常。
+     * 如果指紋已穩定且出現新能力，回傳異常列表。
+     */
+    recordInvocation(skillName: string, event: AgentEvent): readonly BehaviorAnomaly[];
+    /**
+     * Get an immutable fingerprint snapshot for a skill.
+     * 取得某 skill 的不可變指紋快照。
+     */
+    getFingerprint(skillName: string): SkillFingerprint | undefined;
+    /** Get all tracked skill names */
+    getTrackedSkills(): string[];
+    /** Get count of stable fingerprints */
+    getStableCount(): number;
+    /** Get total tracked skills */
+    getTrackedCount(): number;
+    /**
+     * Reset a skill's fingerprint (e.g., after a legitimate update).
+     * 重置 skill 指紋（例如合法更新後）。
+     */
+    resetFingerprint(skillName: string): void;
+    /**
+     * Evict fingerprints not seen since cutoffMs ago.
+     * 清除超過 cutoffMs 未活動的指紋。
+     */
+    cleanup(cutoffMs: number): number;
+    private getOrCreate;
+    private computeCapabilityHash;
+}
+export {};
+//# sourceMappingURL=skill-fingerprint.d.ts.map

package/dist/skill-fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-fingerprint.d.ts","sourceRoot":"","sources":["../src/skill-fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAM7C,mDAAmD;AACnD,UAAU,iBAAiB;IACzB,qDAAqD;IACrD,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5C,4CAA4C;IAC5C,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC7C,yCAAyC;IACzC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,oCAAoC;IACpC,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3C,6EAA6E;IAC7E,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC9C;AAED,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,iBAAiB,CAAC;IACzC,gDAAgD;IAChD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAChB,mBAAmB,GACnB,oBAAoB,GACpB,gBAAgB,GAChB,kBAAkB,GAClB,oBAAoB,GACpB,sBAAsB,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAqGD,MAAM,WAAW,sBAAsB;IACrC,yEAAyE;IACzE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyC;IACtE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,MAAM,CAAC,EAAE,sBAAsB;IAK3C;;;;;;OAMG;IACH,gBAAgB,CACd,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,UAAU,GAChB,SAAS,eAAe,EAAE;IA8H7B;;;OAGG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAqB/D,kCAAkC;IAClC,gBAAgB,IAAI,MAAM,EAAE;IAI5B,uCAAuC;IACvC,cAAc,IAAI,MAAM;IAQxB,+BAA+B;IAC/B,eAAe,IAAI,MAAM;IAIzB;;;OAGG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIzC;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAgBjC,OAAO,CAAC,WAAW;IAkCnB,OAAO,CAAC,qBAAqB;CAU9B"}