safari-pilot 0.1.0

package/dist/security/circuit-breaker.js

@@ -0,0 +1,114 @@
+import { CircuitBreakerOpenError } from '../errors.js';
+const FAILURE_THRESHOLD = 5; // consecutive failures to trip the circuit
+const WINDOW_MS = 60_000; // failure tracking window (60 s)
+const COOLDOWN_MS = 120_000; // open → half-open cooldown (120 s)
+function emptyState() {
+    return {
+        failures: 0,
+        firstFailureAt: 0,
+        openedAt: null,
+        probeAllowed: false,
+        probeInFlight: false,
+    };
+}
+export class CircuitBreaker {
+    states = new Map();
+    // ── Public API ───────────────────────────────────────────────────────────────
+    /**
+     * Record a successful call. Resets the failure counter and closes the circuit.
+     */
+    recordSuccess(domain) {
+        const state = this.getState_(domain);
+        state.failures = 0;
+        state.firstFailureAt = 0;
+        state.openedAt = null;
+        state.probeAllowed = false;
+        state.probeInFlight = false;
+        this.states.set(domain, state);
+    }
+    /**
+     * Record a failed call. May open the circuit if the threshold is reached.
+     */
+    recordFailure(domain) {
+        const now = Date.now();
+        const state = this.getState_(domain);
+        // A probe failure in half-open state immediately re-opens the circuit,
+        // bypassing the normal threshold, and resets the cooldown clock.
+        if (state.probeInFlight) {
+            state.openedAt = now;
+            state.probeAllowed = false;
+            state.probeInFlight = false;
+            // Keep failures at threshold so the circuit stays open on next check
+            state.failures = FAILURE_THRESHOLD;
+            state.firstFailureAt = now;
+            this.states.set(domain, state);
+            return;
+        }
+        // Reset failure count if previous run is outside the tracking window
+        if (state.failures > 0 && now - state.firstFailureAt > WINDOW_MS) {
+            state.failures = 0;
+            state.firstFailureAt = 0;
+        }
+        if (state.failures === 0) {
+            state.firstFailureAt = now;
+        }
+        state.failures += 1;
+        if (state.failures >= FAILURE_THRESHOLD) {
+            state.openedAt = now;
+            state.probeAllowed = false;
+        }
+        this.states.set(domain, state);
+    }
+    /**
+     * Returns true when the circuit is open (calls should be rejected).
+     * Half-open circuits return false — a probe is permitted.
+     */
+    isOpen(domain) {
+        return this.getState(domain) === 'open';
+    }
+    /**
+     * Compute the current circuit state for a domain.
+     */
+    getState(domain) {
+        const state = this.getState_(domain);
+        if (state.openedAt === null) {
+            return 'closed';
+        }
+        const elapsed = Date.now() - state.openedAt;
+        if (elapsed >= COOLDOWN_MS) {
+            return 'half-open';
+        }
+        return 'open';
+    }
+    /**
+     * Assert the circuit is not open before executing a call.
+     * Call this at the entry point of any guarded operation.
+     * Throws CircuitBreakerOpenError when the circuit is open.
+     * In half-open state, marks the probe as issued and allows one call through.
+     */
+    assertClosed(domain) {
+        const circuitState = this.getState(domain);
+        const state = this.getState_(domain);
+        if (circuitState === 'open') {
+            const remaining = COOLDOWN_MS - (Date.now() - (state.openedAt ?? 0));
+            throw new CircuitBreakerOpenError(domain, Math.ceil(remaining / 1000));
+        }
+        if (circuitState === 'half-open') {
+            if (state.probeAllowed) {
+                // Already issued a probe — reject subsequent calls until success/fail
+                throw new CircuitBreakerOpenError(domain, 0);
+            }
+            state.probeAllowed = true;
+            state.probeInFlight = true;
+            this.states.set(domain, state);
+        }
+    }
+    // ── Internal ─────────────────────────────────────────────────────────────────
+    getState_(domain) {
+        if (!this.states.has(domain)) {
+            this.states.set(domain, emptyState());
+        }
+        return this.states.get(domain);
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/security/circuit-breaker.js.map

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

package/dist/security/domain-policy.d.ts

@@ -0,0 +1,29 @@
+type TrustLevel = 'trusted' | 'untrusted' | 'unknown';
+interface PolicyRule {
+    trust: TrustLevel;
+    privateWindow: boolean;
+    extensionAllowed: boolean;
+    maxActionsPerMinute: number;
+}
+export interface EvaluateResult {
+    trust: TrustLevel;
+    privateWindow: boolean;
+    extensionAllowed: boolean;
+    maxActionsPerMinute: number;
+}
+export declare class DomainPolicy {
+    private rules;
+    constructor();
+    addRule(domain: string, policy: Partial<PolicyRule>): void;
+    removeRule(domain: string): void;
+    /**
+     * Evaluate a URL against all stored rules.
+     * Rules are checked in insertion order; first match wins.
+     * Falls back to DEFAULT_POLICY if no rule matches.
+     */
+    evaluate(url: string): EvaluateResult;
+    getRules(): Array<{
+        domain: string;
+    } & PolicyRule>;
+}
+export {};

package/dist/security/domain-policy.js

@@ -0,0 +1,96 @@
+const DEFAULT_POLICY = {
+    trust: 'unknown',
+    privateWindow: false,
+    extensionAllowed: false,
+    maxActionsPerMinute: 60,
+};
+// Built-in sensitive domain patterns → untrusted, force private window
+const SENSITIVE_PATTERNS = [
+    '*.bank.*',
+    '*.banking.*',
+    'paypal.com',
+    '*.paypal.com',
+    'stripe.com',
+    '*.stripe.com',
+    'venmo.com',
+    '*.venmo.com',
+    'chase.com',
+    '*.chase.com',
+    'wellsfargo.com',
+    '*.wellsfargo.com',
+    'bankofamerica.com',
+    '*.bankofamerica.com',
+    'citibank.com',
+    '*.citibank.com',
+];
+const SENSITIVE_POLICY = {
+    trust: 'untrusted',
+    privateWindow: true,
+    extensionAllowed: false,
+    maxActionsPerMinute: 30,
+};
+// ── Glob matching ─────────────────────────────────────────────────────────────
+/**
+ * Convert a glob pattern (only * wildcard supported) to a RegExp.
+ * *.example.com matches sub.example.com but NOT example.com itself.
+ */
+function globToRegex(pattern) {
+    const escaped = pattern
+        .split('*')
+        .map((part) => part.replace(/[.+^${}()|[\]\\]/g, '\\$&'))
+        .join('[^.]+');
+    return new RegExp(`^${escaped}$`, 'i');
+}
+function extractHostname(url) {
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        // If it's already a hostname (no scheme), return as-is
+        return url.toLowerCase();
+    }
+}
+function matchesDomain(pattern, hostname) {
+    if (pattern.includes('*')) {
+        return globToRegex(pattern).test(hostname);
+    }
+    return pattern.toLowerCase() === hostname;
+}
+// ─── DomainPolicy class ───────────────────────────────────────────────────────
+export class DomainPolicy {
+    rules = new Map();
+    constructor() {
+        // Register built-in sensitive domain rules
+        for (const pattern of SENSITIVE_PATTERNS) {
+            this.rules.set(pattern, { ...SENSITIVE_POLICY });
+        }
+    }
+    // ── Rule management ─────────────────────────────────────────────────────────
+    addRule(domain, policy) {
+        const existing = this.rules.get(domain) ?? { ...DEFAULT_POLICY };
+        this.rules.set(domain, { ...existing, ...policy });
+    }
+    removeRule(domain) {
+        this.rules.delete(domain);
+    }
+    // ── Evaluation ──────────────────────────────────────────────────────────────
+    /**
+     * Evaluate a URL against all stored rules.
+     * Rules are checked in insertion order; first match wins.
+     * Falls back to DEFAULT_POLICY if no rule matches.
+     */
+    evaluate(url) {
+        const hostname = extractHostname(url);
+        for (const [pattern, rule] of this.rules) {
+            if (matchesDomain(pattern, hostname)) {
+                return { ...rule };
+            }
+        }
+        return { ...DEFAULT_POLICY };
+    }
+    // ── Introspection ────────────────────────────────────────────────────────────
+    getRules() {
+        return Array.from(this.rules.entries()).map(([domain, rule]) => ({ domain, ...rule }));
+    }
+}
+//# sourceMappingURL=domain-policy.js.map

package/dist/security/domain-policy.js.map

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

package/dist/security/human-approval.d.ts

@@ -0,0 +1,20 @@
+export interface ApprovalResult {
+    required: boolean;
+    reason?: string;
+    category?: string;
+}
+export declare class HumanApproval {
+    /**
+     * Inspect an action/url/params combination and return whether human approval
+     * is required. Returns `{ required: false }` for benign actions, or
+     * `{ required: true, reason, category }` for sensitive ones.
+     *
+     * Does NOT throw — use `assertApproved` for a throwing guard.
+     */
+    requiresApproval(action: string, url: string, params?: Record<string, unknown>): ApprovalResult;
+    /**
+     * Guard variant: throws `HumanApprovalRequiredError` when approval is needed.
+     * Use in tool pipelines where blocking is the correct behaviour.
+     */
+    assertApproved(action: string, url: string, params?: Record<string, unknown>): void;
+}

package/dist/security/human-approval.js

@@ -0,0 +1,150 @@
+import { HumanApprovalRequiredError } from '../errors.js';
+// ─── Pattern Registry ─────────────────────────────────────────────────────────
+/** OAuth / SSO provider URL patterns. */
+const OAUTH_URL_PATTERNS = [
+    /accounts\.google\.com\/o\/oauth/i,
+    /login\.microsoftonline\.com/i,
+    /github\.com\/login\/oauth/i,
+    /auth0\.com/i,
+    /okta\.com/i,
+    /login\.live\.com/i,
+    /appleid\.apple\.com/i,
+    /facebook\.com\/dialog\/oauth/i,
+];
+/** Financial checkout / payment URL patterns. */
+const FINANCIAL_URL_PATTERNS = [
+    /paypal\.com\/checkout/i,
+    /paypal\.com\/pay/i,
+    /stripe\.com\/pay/i,
+    /checkout\.stripe\.com/i,
+    /pay\.amazon\.com/i,
+    /venmo\.com\/pay/i,
+];
+/** Sensitive financial form field names. */
+const FINANCIAL_FIELD_NAMES = [
+    /^card[_-]?number$/i,
+    /^cvv$/i,
+    /^cvc$/i,
+    /^account[_-]?number$/i,
+    /^routing[_-]?number$/i,
+    /^bank[_-]?account$/i,
+    /^credit[_-]?card$/i,
+];
+/** Downloadable file extensions that require approval. */
+const DOWNLOAD_EXTENSIONS = /\.(exe|dmg|pkg|zip|tar|gz|rar|deb|rpm|msi|app|apk)(\?.*)?$/i;
+/** Account-mutating / high-risk URL path patterns. */
+const ACCOUNT_SETTINGS_PATTERNS = [
+    /\/settings\/security/i,
+    /\/account\/delete/i,
+    /\/password\/change/i,
+    /\/password\/reset/i,
+    /\/delete[_-]?account/i,
+    /\/security\/two-factor/i,
+];
+/** Sensitive field names in form submissions. */
+const SENSITIVE_FORM_FIELDS = [
+    /^password$/i,
+    /^passwd$/i,
+    /^pass$/i,
+    /^ssn$/i,
+    /^social[_-]?security/i,
+    /^credit[_-]?card/i,
+    /^card[_-]?number/i,
+    /^cvv$/i,
+    /^cvc$/i,
+];
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function matchesAny(value, patterns) {
+    return patterns.some((p) => p.test(value));
+}
+function extractDomain(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return url;
+    }
+}
+// ─── HumanApproval ───────────────────────────────────────────────────────────
+export class HumanApproval {
+    /**
+     * Inspect an action/url/params combination and return whether human approval
+     * is required. Returns `{ required: false }` for benign actions, or
+     * `{ required: true, reason, category }` for sensitive ones.
+     *
+     * Does NOT throw — use `assertApproved` for a throwing guard.
+     */
+    requiresApproval(action, url, params) {
+        // 1. OAuth / SSO flows
+        if (matchesAny(url, OAUTH_URL_PATTERNS)) {
+            return {
+                required: true,
+                category: 'oauth',
+                reason: 'URL matches an OAuth/SSO authentication flow',
+            };
+        }
+        // 2. Financial checkout / payment pages
+        if (matchesAny(url, FINANCIAL_URL_PATTERNS)) {
+            return {
+                required: true,
+                category: 'financial',
+                reason: 'URL matches a financial payment or checkout flow',
+            };
+        }
+        // 3. Financial form fields in params
+        if (params !== undefined) {
+            const fieldNames = Object.keys(params);
+            const sensitiveField = fieldNames.find((f) => matchesAny(f, FINANCIAL_FIELD_NAMES));
+            if (sensitiveField !== undefined) {
+                return {
+                    required: true,
+                    category: 'financial',
+                    reason: `Request contains sensitive financial field: "${sensitiveField}"`,
+                };
+            }
+        }
+        // 4. Download actions or downloadable file extensions in URL
+        if (action === 'download' || DOWNLOAD_EXTENSIONS.test(url)) {
+            return {
+                required: true,
+                category: 'download',
+                reason: 'Action involves downloading a file',
+            };
+        }
+        // 5. Account settings / destructive account operations
+        if (matchesAny(url, ACCOUNT_SETTINGS_PATTERNS)) {
+            return {
+                required: true,
+                category: 'account_settings',
+                reason: 'URL matches a sensitive account settings or deletion path',
+            };
+        }
+        // 6. Form submissions (POST) with sensitive field names
+        if (action === 'submit' || action === 'post') {
+            if (params !== undefined) {
+                const fieldNames = Object.keys(params);
+                const sensitiveField = fieldNames.find((f) => matchesAny(f, SENSITIVE_FORM_FIELDS));
+                if (sensitiveField !== undefined) {
+                    return {
+                        required: true,
+                        category: 'form_submission',
+                        reason: `Form submission contains sensitive field: "${sensitiveField}"`,
+                    };
+                }
+            }
+        }
+        return { required: false };
+    }
+    /**
+     * Guard variant: throws `HumanApprovalRequiredError` when approval is needed.
+     * Use in tool pipelines where blocking is the correct behaviour.
+     */
+    assertApproved(action, url, params) {
+        const result = this.requiresApproval(action, url, params);
+        if (result.required) {
+            const domain = extractDomain(url);
+            throw new HumanApprovalRequiredError(action, domain);
+        }
+    }
+}
+//# sourceMappingURL=human-approval.js.map

package/dist/security/human-approval.js.map

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

package/dist/security/idpi-scanner.d.ts

@@ -0,0 +1,20 @@
+export interface IdpiThreat {
+    pattern: string;
+    confidence: number;
+    match: string;
+}
+export interface ScanResult {
+    safe: boolean;
+    threats: IdpiThreat[];
+}
+export declare class IdpiScanner {
+    /**
+     * Scan a text string for indirect prompt injection patterns.
+     *
+     * Returns a result with:
+     * - `safe` — false when any threat confidence exceeds 0.5
+     * - `threats` — all matched threats with their pattern name, confidence, and
+     *               the excerpt that triggered the match
+     */
+    scan(text: string): ScanResult;
+}

package/dist/security/idpi-scanner.js

@@ -0,0 +1,102 @@
+// ─── IdpiScanner ─────────────────────────────────────────────────────────────
+//
+// Indirect Prompt Injection (IDPI) defence layer. Scans arbitrary text content
+// retrieved from web pages for patterns that attempt to hijack agent behaviour.
+//
+// Each detector is a named rule with a confidence weight (0.0–1.0). A result
+// is marked unsafe when any matched threat has confidence > 0.5.
+// ─── Pattern Registry ─────────────────────────────────────────────────────────
+const PATTERN_RULES = [
+    // 1. Instruction override attempts
+    {
+        name: 'instruction_override',
+        regex: /ignore\s+(previous|prior|all\s+prior|above)\s+instructions?|disregard\s+(the\s+)?(above|previous|prior)/gi,
+        confidence: 0.95,
+    },
+    // 2. Role reassignment attempts
+    {
+        name: 'role_reassignment',
+        regex: /you\s+are\s+now\s+(a|an)\s+\w+|you\s+are\s+a\s+\w+/gi,
+        confidence: 0.80,
+    },
+    // 3. Fake system prompt injection
+    {
+        name: 'fake_system_prompt',
+        regex: /^system:|^SYSTEM:|###\s*System\b/gim,
+        confidence: 0.90,
+    },
+    // 4. Base64-encoded payloads (50+ contiguous base64 chars)
+    {
+        name: 'base64_payload',
+        regex: /[A-Za-z0-9+/]{50,}={0,2}/g,
+        confidence: 0.65,
+    },
+    // 5. Secrecy / concealment instructions
+    {
+        name: 'secrecy_instruction',
+        regex: /do\s+not\s+tell\s+(the\s+)?user|keep\s+this\s+secret|don['']?t\s+mention\s+this/gi,
+        confidence: 0.90,
+    },
+    // 6. HTML-encoded instruction sequences (&#x...; or &#...;)
+    {
+        name: 'html_encoded_instruction',
+        regex: /(?:&#x[0-9a-fA-F]{2,4};){4,}|(?:&#\d{2,5};){4,}/g,
+        confidence: 0.75,
+    },
+    // 7. CSS content property with non-trivial text
+    {
+        name: 'css_content_injection',
+        regex: /content\s*:\s*["'][^"']{10,}["']/gi,
+        confidence: 0.70,
+    },
+    // 8. Hidden text patterns via CSS
+    {
+        name: 'hidden_text',
+        regex: /display\s*:\s*none|visibility\s*:\s*hidden|font-size\s*:\s*0(px|pt|em|rem)?/gi,
+        confidence: 0.60,
+    },
+    // 9. Unicode homoglyph attacks — non-ASCII characters mixed into Latin words
+    {
+        name: 'unicode_homoglyph',
+        regex: /[^\x00-\x7F\s]{1}[a-zA-Z]{2,}|[a-zA-Z]{2,}[^\x00-\x7F\s]{1}/g,
+        confidence: 0.75,
+    },
+];
+// ─── IdpiScanner ─────────────────────────────────────────────────────────────
+export class IdpiScanner {
+    /**
+     * Scan a text string for indirect prompt injection patterns.
+     *
+     * Returns a result with:
+     * - `safe` — false when any threat confidence exceeds 0.5
+     * - `threats` — all matched threats with their pattern name, confidence, and
+     *               the excerpt that triggered the match
+     */
+    scan(text) {
+        const threats = [];
+        for (const rule of PATTERN_RULES) {
+            // Reset lastIndex so repeated calls work correctly on global regexes
+            rule.regex.lastIndex = 0;
+            let match;
+            const seen = new Set();
+            while ((match = rule.regex.exec(text)) !== null) {
+                const excerpt = match[0].slice(0, 100); // cap excerpt length
+                if (seen.has(excerpt))
+                    continue; // deduplicate identical matches
+                seen.add(excerpt);
+                threats.push({
+                    pattern: rule.name,
+                    confidence: rule.confidence,
+                    match: excerpt,
+                });
+                // Prevent infinite loops on zero-length matches
+                if (match.index === rule.regex.lastIndex) {
+                    rule.regex.lastIndex++;
+                }
+            }
+        }
+        const safe = threats.every((t) => t.confidence <= 0.5);
+        return { safe, threats };
+    }
+}
+//# sourceMappingURL=idpi-scanner.js.map

package/dist/security/idpi-scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idpi-scanner.js","sourceRoot":"","sources":["../../src/security/idpi-scanner.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,iEAAiE;AAmBjE,iFAAiF;AAEjF,MAAM,aAAa,GAAkB;IACnC,mCAAmC;IACnC;QACE,IAAI,EAAE,sBAAsB;QAC5B,KAAK,EAAE,2GAA2G;QAClH,UAAU,EAAE,IAAI;KACjB;IAED,gCAAgC;IAChC;QACE,IAAI,EAAE,mBAAmB;QACzB,KAAK,EAAE,sDAAsD;QAC7D,UAAU,EAAE,IAAI;KACjB;IAED,kCAAkC;IAClC;QACE,IAAI,EAAE,oBAAoB;QAC1B,KAAK,EAAE,qCAAqC;QAC5C,UAAU,EAAE,IAAI;KACjB;IAED,2DAA2D;IAC3D;QACE,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,2BAA2B;QAClC,UAAU,EAAE,IAAI;KACjB;IAED,wCAAwC;IACxC;QACE,IAAI,EAAE,qBAAqB;QAC3B,KAAK,EAAE,mFAAmF;QAC1F,UAAU,EAAE,IAAI;KACjB;IAED,4DAA4D;IAC5D;QACE,IAAI,EAAE,0BAA0B;QAChC,KAAK,EAAE,kDAAkD;QACzD,UAAU,EAAE,IAAI;KACjB;IAED,gDAAgD;IAChD;QACE,IAAI,EAAE,uBAAuB;QAC7B,KAAK,EAAE,oCAAoC;QAC3C,UAAU,EAAE,IAAI;KACjB;IAED,kCAAkC;IAClC;QACE,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,+EAA+E;QACtF,UAAU,EAAE,IAAI;KACjB;IAED,6EAA6E;IAC7E;QACE,IAAI,EAAE,mBAAmB;QACzB,KAAK,EAAE,8DAA8D;QACrE,UAAU,EAAE,IAAI;KACjB;CACF,CAAC;AAEF,gFAAgF;AAEhF,MAAM,OAAO,WAAW;IACtB;;;;;;;OAOG;IACH,IAAI,CAAC,IAAY;QACf,MAAM,OAAO,GAAiB,EAAE,CAAC;QAEjC,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;YACjC,qEAAqE;YACrE,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC;YAEzB,IAAI,KAA6B,CAAC;YAClC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;YAE/B,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;gBAChD,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,qBAAqB;gBAC7D,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;oBAAE,SAAS,CAAC,gCAAgC;gBACjE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBAElB,OAAO,CAAC,IAAI,CAAC;oBACX,OAAO,EAAE,IAAI,CAAC,IAAI;oBAClB,UAAU,EAAE,IAAI,CAAC,UAAU;oBAC3B,KAAK,EAAE,OAAO;iBACf,CAAC,CAAC;gBAEH,gDAAgD;gBAChD,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;oBACzC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;gBACzB,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,IAAI,GAAG,CAAC,CAAC;QAEvD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC3B,CAAC;CACF"}

package/dist/security/kill-switch.d.ts

@@ -0,0 +1,51 @@
+import { AuditLog } from './audit-log.js';
+export interface ActivationState {
+    active: boolean;
+    reason?: string;
+    activatedAt?: string;
+}
+export interface AutoActivationThreshold {
+    /** Number of errors that triggers auto-activation. */
+    maxErrors: number;
+    /** Rolling window (seconds) within which errors are counted. */
+    windowSeconds: number;
+}
+export declare class KillSwitch {
+    private _active;
+    private _reason;
+    private _activatedAt;
+    private readonly auditLog;
+    private readonly threshold;
+    private readonly errorWindow;
+    constructor(options?: {
+        auditLog?: AuditLog;
+        autoActivation?: AutoActivationThreshold;
+    });
+    /**
+     * Activate the kill switch. All subsequent `checkBeforeAction` calls will
+     * throw `KillSwitchActiveError` until `deactivate` is called.
+     */
+    activate(reason: string): void;
+    /**
+     * Deactivate the kill switch, re-enabling automation.
+     */
+    deactivate(): void;
+    /**
+     * Returns true if the kill switch is currently active.
+     */
+    isActive(): boolean;
+    /**
+     * Returns the current activation state including reason and timestamp.
+     */
+    getActivation(): ActivationState;
+    /**
+     * Call before every automation action. Throws `KillSwitchActiveError` if the
+     * kill switch is active, otherwise returns normally.
+     */
+    checkBeforeAction(): void;
+    /**
+     * Record an error event. If the configured threshold is exceeded within the
+     * rolling window, the kill switch auto-activates.
+     */
+    recordError(): void;
+}