autokap 1.0.0

package/dist/security.d.ts

@@ -0,0 +1,20 @@
+import type { ActionType, AgentConfig, CaptureObjective, CaptureRepairCause, InteractiveElement } from './types.js';
+export interface SecurityContext {
+    rootUrl?: string;
+    currentUrl?: string;
+    credentials?: AgentConfig['credentials'];
+    interactiveElements: InteractiveElement[];
+    currentLang?: string;
+    currentTheme?: 'light' | 'dark';
+    runMode?: AgentConfig['runMode'];
+    currentObjective?: CaptureObjective;
+    activeRepairCause?: CaptureRepairCause | null;
+}
+export interface SecurityDecision {
+    allowed: boolean;
+    reason?: string;
+    target?: InteractiveElement | null;
+}
+export declare function evaluateResolvedActionSecurity(action: ActionType, args: Record<string, unknown>, context: SecurityContext, target: InteractiveElement | null): SecurityDecision;
+export declare function evaluateActionSecurity(action: ActionType, args: Record<string, unknown>, context: SecurityContext): SecurityDecision;
+export declare function describeSecurityTarget(target: InteractiveElement | null | undefined): string;

package/dist/security.js

@@ -0,0 +1,569 @@
+const AUTH_URL_RE = /\b(login|log-in|signin|sign-in|auth|session|password|otp|verify|2fa|connexion|connect|identif|acceder|anmeldung|beta|invite|access|early-access|waitlist)\b/i;
+const AUTH_ACTION_RE = /\b(log ?in|sign ?in|se connecter|connexion|continue|continuer|next|suivant|verify|verifier|submit|soumettre|use email|email|e-mail|password|mot de passe|otp|code|enter|entrer|unlock|access|acceder)\b/i;
+const AUTH_ENTRY_RE = /\b(log ?in|sign ?in|se connecter|connexion|continue with email|continuer avec l[‘’]?e-?mail|sign ?in with email|log ?in with email|connexion par email|use email|use password)\b/i;
+const AUTH_SUBMIT_RE = /\b(continue|continuer|next|suivant|verify|verifier|submit|soumettre|otp|code|unlock|access|acceder|enter|entrer)\b/i;
+const AUTH_FIELD_RE = /\b(email|e-mail|username|user name|identifiant|login|mot de passe|password|passcode|otp|verification code|code|beta|invite|invitation|access.?code|access.?key|cl[eé] d’acc[eè]s|code d’acc[eè]s|code d’invitation)\b/i;
+const SEARCH_FIELD_RE = /\b(search|recherche|filter|filtre|query|keyword|find|lookup)\b/i;
+const TYPE_BLOCK_RE = /\b(comment|message|reply|chat|prompt|post|tweet|caption|description|bio|status|content|body)\b/i;
+const DANGEROUS_RE = /\b(delete|remove|destroy|deactivate|disable|disconnect|unlink|revoke|regenerate|archive|trash|wipe|terminate|logout|log out|sign out|buy|purchase|checkout|pay|order|book|subscribe|upgrade|acheter|payer|checkout|commander|supprimer|effacer|desactiver|deconnecter|cancel subscription|close account|delete account)\b/i;
+const MUTATING_RE = /\b(save|submit|publish|post|send|reply|comment|share|invite|upload|import|apply|approve|merge|sync|commit|confirm|validate|soumettre|valider|envoyer|publier|partager)\b/i;
+const CREATIVE_RE = /\b(generate|continue with ai|ai generate|auto.?generate|compose|draft|write with ai|produce|fabricate|synthesize|g[eé]n[eé]rer avec|cr[eé]er avec l['']?ia|r[eé]diger|continuer avec l['']?ia|continuer avec ai)\b/i;
+const INPUT_FOCUS_RE = /\b(email|e-mail|username|user name|identifiant|login|mot de passe|password|passcode|otp|verification code|code|beta|invite|invitation|access.?code|access.?key|search|recherche|filter|filtre|query|keyword|find|lookup)\b/i;
+const TOGGLE_ROLE_RE = /\b(switch|checkbox|radio|menuitemcheckbox|menuitemradio)\b/i;
+const BUTTON_ROLE_RE = /\b(button)\b/i;
+const EXPAND_TRIGGER_RE = /\b(menu|navigation|nav|more|show|open|expand|details|accordion|filter|filters|sort|language|locale|theme|account|profile|settings|categories|sections|faq|plans|pricing)\b/i;
+const LANGUAGE_CONTROL_RE = /\b(lang|locale|language|langue|idioma|sprache|lingua|hreflang)\b/i;
+const THEME_CONTROL_RE = /\b(theme|appearance|mode|dark|light|clair|sombre|oscuro|claro|dunkel|hell|color.?scheme)\b/i;
+const SHARED_HOSTING_SUFFIXES = [
+    'github.io',
+    'vercel.app',
+    'netlify.app',
+    'pages.dev',
+    'workers.dev',
+    'surge.sh',
+    'web.app',
+    'firebaseapp.com',
+    'herokuapp.com',
+    'onrender.com',
+    'azurewebsites.net',
+    'cloudfront.net',
+    'appspot.com',
+];
+const ALLOWED_KEYS = new Set([
+    'Escape',
+    'Tab',
+    'ArrowUp',
+    'ArrowDown',
+    'ArrowLeft',
+    'ArrowRight',
+    'PageUp',
+    'PageDown',
+    'Home',
+    'End',
+]);
+const MAX_TYPED_TEXT_LENGTH = 256;
+const LANGUAGE_ALIASES = [
+    'ar', 'arabic', 'arab', 'العربية',
+    'cs', 'czech', 'cesky', 'čeština',
+    'da', 'danish', 'dansk',
+    'de', 'german', 'deutsch',
+    'en', 'english',
+    'es', 'spanish', 'espanol', 'español',
+    'fi', 'finnish', 'suomi',
+    'fr', 'french', 'francais', 'français',
+    'hu', 'hungarian', 'magyar',
+    'it', 'italian', 'italiano',
+    'ja', 'japanese', 'japonais', '日本語',
+    'ko', 'korean', '한국어',
+    'nl', 'dutch', 'nederlands',
+    'norwegian', 'norsk',
+    'pl', 'polish', 'polski',
+    'pt', 'portuguese', 'portugues', 'português',
+    'ru', 'russian', 'русский',
+    'sv', 'swedish', 'svenska',
+    'tr', 'turkish', 'turkce', 'türkçe',
+    'zh', 'chinese', '中文',
+];
+const THEME_ALIASES = ['light', 'dark', 'clair', 'sombre', 'claro', 'oscuro', 'hell', 'dunkel'];
+function parseHttpUrl(value) {
+    if (!value)
+        return null;
+    try {
+        const parsed = new URL(value);
+        if (!['http:', 'https:'].includes(parsed.protocol))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function effectivePort(url) {
+    if (url.port)
+        return url.port;
+    return url.protocol === 'https:' ? '443' : '80';
+}
+function isIpv4Hostname(hostname) {
+    return /^\d{1,3}(?:\.\d{1,3}){3}$/.test(hostname);
+}
+function isIpv6Hostname(hostname) {
+    return hostname.includes(':');
+}
+function isLocalHostname(hostname) {
+    if (hostname === 'localhost' || hostname === '::1')
+        return true;
+    if (hostname.endsWith('.localhost'))
+        return true;
+    if (!isIpv4Hostname(hostname))
+        return false;
+    const [a, b] = hostname.split('.').map(Number);
+    return a === 127
+        || a === 10
+        || (a === 192 && b === 168)
+        || (a === 172 && b >= 16 && b <= 31);
+}
+function isSharedHostingHostname(hostname) {
+    return SHARED_HOSTING_SUFFIXES.some(suffix => hostname === suffix || hostname.endsWith(`.${suffix}`));
+}
+function normalizeScopeHostname(hostname) {
+    return hostname.startsWith('www.') ? hostname.slice(4) : hostname;
+}
+function buildNavigationScopes(context) {
+    const sources = [
+        context.rootUrl,
+        context.credentials?.loginUrl,
+    ];
+    const dedup = new Map();
+    for (const value of sources) {
+        const parsed = parseHttpUrl(value);
+        if (!parsed)
+            continue;
+        const hostname = parsed.hostname.toLowerCase();
+        const exactHost = isLocalHostname(hostname) || isIpv4Hostname(hostname) || isIpv6Hostname(hostname) || isSharedHostingHostname(hostname);
+        const scopeHostname = exactHost ? hostname : normalizeScopeHostname(hostname);
+        const scope = {
+            hostname: scopeHostname,
+            port: effectivePort(parsed),
+            exactHost,
+        };
+        dedup.set(`${scope.hostname}:${scope.port}:${scope.exactHost ? 'exact' : 'family'}`, scope);
+    }
+    return Array.from(dedup.values());
+}
+function isWithinProjectScope(candidate, scopes) {
+    const hostname = candidate.hostname.toLowerCase();
+    const port = effectivePort(candidate);
+    return scopes.some(scope => {
+        if (scope.exactHost) {
+            return hostname === scope.hostname && port === scope.port;
+        }
+        return (hostname === scope.hostname || hostname.endsWith(`.${scope.hostname}`));
+    });
+}
+function combineElementText(el) {
+    return [el.text, el.ariaLabel, el.href, el.inputType, el.role]
+        .filter(Boolean)
+        .join(' ')
+        .toLowerCase();
+}
+function normalizeVariantText(value) {
+    return (value ?? '')
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase();
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function textContainsAlias(haystack, alias) {
+    const normalizedAlias = normalizeVariantText(alias);
+    if (!normalizedAlias)
+        return false;
+    if (/^[a-z]{2,3}$/.test(normalizedAlias)) {
+        return new RegExp(`(^|[^a-z])${escapeRegExp(normalizedAlias)}([^a-z]|$)`, 'i').test(haystack);
+    }
+    return haystack.includes(normalizedAlias);
+}
+function collectVariantTargetText(target) {
+    return normalizeVariantText([
+        target.text,
+        target.ariaLabel,
+        target.href,
+        target.selector,
+        target.role,
+        target.inputType,
+    ]
+        .filter(Boolean)
+        .join(' '));
+}
+function hasVariantAdjustmentContext(context) {
+    return context.runMode === 'language_preflight'
+        || context.currentObjective === 'repair'
+        || context.activeRepairCause === 'lang'
+        || context.activeRepairCause === 'theme'
+        || !!context.currentLang
+        || !!context.currentTheme;
+}
+function looksLikeLanguageControlTarget(target, context) {
+    const text = collectVariantTargetText(target);
+    if (!text)
+        return false;
+    if (LANGUAGE_CONTROL_RE.test(text))
+        return true;
+    if (/\b(data-lang|data-locale|lang=|locale=|hreflang)\b/i.test(text))
+        return true;
+    if (context.currentLang && textContainsAlias(text, context.currentLang))
+        return true;
+    return LANGUAGE_ALIASES.some(alias => textContainsAlias(text, alias));
+}
+function looksLikeThemeControlTarget(target, context) {
+    const text = collectVariantTargetText(target);
+    if (!text)
+        return false;
+    if (THEME_CONTROL_RE.test(text))
+        return true;
+    if (/\b(data-theme|theme=|color-scheme)\b/i.test(text))
+        return true;
+    if (context.currentTheme && textContainsAlias(text, context.currentTheme))
+        return true;
+    return THEME_ALIASES.some(alias => textContainsAlias(text, alias));
+}
+function isSafeVariantToggleTarget(target, context) {
+    if (!hasVariantAdjustmentContext(context))
+        return false;
+    return looksLikeLanguageControlTarget(target, context)
+        || looksLikeThemeControlTarget(target, context);
+}
+function inferAuthContext(context) {
+    // Objective check 1: URL explicitly indicates an auth flow
+    const currentUrl = (context.currentUrl || '').toLowerCase();
+    if (AUTH_URL_RE.test(currentUrl))
+        return true;
+    // Objective check 2: page has a password input field — strong auth signal
+    const hasPasswordField = context.interactiveElements.some(el => el.inputType === 'password');
+    if (hasPasswordField)
+        return true;
+    // Auth field/action text matching is only trusted when combined with
+    // a password field or auth URL. A standalone email field could be
+    // a newsletter signup, not an auth form.
+    // The gate pattern (few text inputs, no textarea) is removed — it was
+    // too broad and could match contact forms, search pages, or settings.
+    return false;
+}
+function isAllowedNavigation(candidateUrl, context) {
+    try {
+        const base = context.currentUrl || context.rootUrl || 'https://example.com';
+        const parsed = new URL(candidateUrl, base);
+        if (!['http:', 'https:'].includes(parsed.protocol))
+            return false;
+        const scopes = buildNavigationScopes(context);
+        if (scopes.length === 0)
+            return false;
+        return isWithinProjectScope(parsed, scopes);
+    }
+    catch {
+        return false;
+    }
+}
+function resolveTargetFromAction(args, interactiveElements) {
+    if (args.index !== undefined) {
+        return interactiveElements.find(el => el.index === args.index) || null;
+    }
+    if (args.selector) {
+        return interactiveElements.find(el => el.selector === args.selector) || null;
+    }
+    if (args.x !== undefined && args.y !== undefined) {
+        const x = args.x;
+        const y = args.y;
+        return interactiveElements.find(el => {
+            const bb = el.boundingBox;
+            return !!bb && x >= bb.x && x <= bb.x + bb.width && y >= bb.y && y <= bb.y + bb.height;
+        }) || null;
+    }
+    return null;
+}
+function isButtonLike(target) {
+    return target.tag === 'button'
+        || BUTTON_ROLE_RE.test(target.role)
+        || ['button', 'submit', 'reset', 'image'].includes(target.inputType || '');
+}
+function isToggleLike(target) {
+    return TOGGLE_ROLE_RE.test(target.role)
+        || ['checkbox', 'radio'].includes(target.inputType || '');
+}
+function isTextEntryTarget(target) {
+    if (target.tag === 'textarea')
+        return true;
+    if (target.tag === 'input') {
+        const type = (target.inputType || 'text').toLowerCase();
+        return !['submit', 'button', 'checkbox', 'radio', 'file', 'hidden', 'image', 'reset'].includes(type);
+    }
+    return INPUT_FOCUS_RE.test(combineElementText(target));
+}
+function isSelectLikeTarget(target) {
+    return target.tag === 'select'
+        || target.inputType === 'select'
+        || /\b(combobox|listbox)\b/i.test(target.role);
+}
+function isDisclosureLikeTarget(target) {
+    return target.tag === 'summary'
+        || (target.ariaExpanded !== undefined && target.ariaExpanded !== null)
+        || !!target.ariaControls
+        || !!target.ariaHasPopup;
+}
+function evaluateClickTarget(target, context) {
+    const text = combineElementText(target);
+    const authContext = inferAuthContext(context);
+    const hasLabel = !!(target.text || target.ariaLabel || target.href);
+    if (target.inputType === 'submit' && !authContext) {
+        return { allowed: false, reason: 'Blocked by security policy: submit buttons are only allowed during authentication.', target };
+    }
+    if (target.inputType === 'file') {
+        return { allowed: false, reason: 'Blocked by security policy: file upload controls are not allowed.', target };
+    }
+    if (target.href && !isAllowedNavigation(target.href, context)) {
+        return { allowed: false, reason: 'Blocked by security policy: external navigation is not allowed.', target };
+    }
+    if (DANGEROUS_RE.test(text)) {
+        return { allowed: false, reason: 'Blocked by security policy: destructive, financial, logout, or account-changing action.', target };
+    }
+    if (CREATIVE_RE.test(text)) {
+        return { allowed: false, reason: 'Blocked by security policy: creative/generative action that would create or modify content via AI.', target };
+    }
+    if (MUTATING_RE.test(text)) {
+        if (authContext && AUTH_ACTION_RE.test(text)) {
+            return { allowed: true, target };
+        }
+        return { allowed: false, reason: 'Blocked by security policy: content creation/update or form submission action.', target };
+    }
+    if (isToggleLike(target)) {
+        if (isSafeVariantToggleTarget(target, context)) {
+            return { allowed: true, target };
+        }
+        return { allowed: false, reason: 'Blocked by security policy: toggles, checkboxes, and radio controls are not allowed.', target };
+    }
+    const isSubmitLike = target.inputType === 'submit'
+        || target.tag === 'button'
+        || target.role.includes('button');
+    if (isSubmitLike && AUTH_ENTRY_RE.test(text)) {
+        return { allowed: true, target };
+    }
+    if (isSubmitLike && AUTH_SUBMIT_RE.test(text) && !authContext) {
+        return { allowed: false, reason: 'Blocked by security policy: submit-like action outside authentication flow.', target };
+    }
+    if (isTextEntryTarget(target)) {
+        return { allowed: true, target };
+    }
+    if (target.href) {
+        return { allowed: true, target };
+    }
+    // Unlabeled buttons are allowed — blocking them prevents the agent from
+    // clicking close/dismiss/icon buttons (×) which are safe UI operations.
+    // Dangerous actions are already caught by DANGEROUS_RE, MUTATING_RE, and CREATIVE_RE
+    // checks above, which match on text content. An unlabeled button has no text to match,
+    // so it cannot be a known dangerous action.
+    return { allowed: true, target };
+}
+function evaluateTypingTarget(target, typedText, context) {
+    const text = combineElementText(target);
+    const authContext = inferAuthContext(context);
+    if (typedText.length > MAX_TYPED_TEXT_LENGTH) {
+        return { allowed: false, reason: `Blocked by security policy: typed text exceeds ${MAX_TYPED_TEXT_LENGTH} characters.`, target };
+    }
+    if (/[\r\n]/.test(typedText)) {
+        return { allowed: false, reason: 'Blocked by security policy: multi-line text entry is not allowed.', target };
+    }
+    if (target.tag === 'textarea') {
+        return { allowed: false, reason: 'Blocked by security policy: typing into textareas is not allowed.', target };
+    }
+    if (['submit', 'button', 'checkbox', 'radio', 'file', 'hidden'].includes(target.inputType || '')) {
+        return { allowed: false, reason: 'Blocked by security policy: target field is not a safe text input.', target };
+    }
+    if (TYPE_BLOCK_RE.test(text)) {
+        return { allowed: false, reason: 'Blocked by security policy: content-composition field.', target };
+    }
+    if (authContext) {
+        return { allowed: true, target };
+    }
+    if (target.inputType === 'search' || SEARCH_FIELD_RE.test(text)) {
+        return { allowed: true, target };
+    }
+    // Default: allow typing into text-like inputs that passed all safety checks above
+    // (not a textarea, not a content-composition field, not a non-text input type)
+    return { allowed: true, target };
+}
+export function evaluateResolvedActionSecurity(action, args, context, target) {
+    if (action === 'click' || action === 'hover') {
+        if (!target)
+            return { allowed: false, reason: 'Blocked by security policy: unresolved target.' };
+        return evaluateClickTarget(target, context);
+    }
+    if (action === 'type_text') {
+        if (!target) {
+            return {
+                allowed: false,
+                reason: 'Blocked by security policy: free-form typing without a known target input is not allowed.',
+            };
+        }
+        return evaluateTypingTarget(target, String(args.text || ''), context);
+    }
+    if (action === 'select_option') {
+        if (!target) {
+            return {
+                allowed: false,
+                reason: 'Blocked by security policy: selecting an option requires a known target control.',
+            };
+        }
+        if (!isSelectLikeTarget(target)) {
+            return {
+                allowed: false,
+                reason: 'Blocked by security policy: target control is not a select-like input.',
+                target,
+            };
+        }
+        const optionText = [
+            args.optionLabel,
+            args.optionValue,
+            typeof args.optionIndex === 'number' ? String(args.optionIndex) : '',
+        ]
+            .filter(Boolean)
+            .join(' ')
+            .toLowerCase();
+        if (!optionText) {
+            return {
+                allowed: false,
+                reason: 'Blocked by security policy: no dropdown option was specified.',
+                target,
+            };
+        }
+        if (optionText.length > MAX_TYPED_TEXT_LENGTH) {
+            return {
+                allowed: false,
+                reason: `Blocked by security policy: option text exceeds ${MAX_TYPED_TEXT_LENGTH} characters.`,
+                target,
+            };
+        }
+        if (DANGEROUS_RE.test(optionText) || MUTATING_RE.test(optionText)) {
+            return {
+                allowed: false,
+                reason: 'Blocked by security policy: selected option looks high-risk or mutating.',
+                target,
+            };
+        }
+        return { allowed: true, target };
+    }
+    if (action === 'safe_expand') {
+        if (!target) {
+            return {
+                allowed: false,
+                reason: 'Blocked by security policy: expanding a panel requires a known target control.',
+            };
+        }
+        const text = combineElementText(target);
+        const disclosureLike = isDisclosureLikeTarget(target);
+        const labeled = !!(target.text || target.ariaLabel);
+        if (target.href) {
+            return {
+                allowed: false,
+                reason: 'Blocked by security policy: safe_expand cannot be used on navigation links.',
+                target,
+            };
+        }
+        if (target.inputType === 'file') {
+            return {
+                allowed: false,
+                reason: 'Blocked by security policy: file upload controls are not allowed.',
+                target,
+            };
+        }
+        if (target.inputType === 'submit') {
+            return {
+                allowed: false,
+                reason: 'Blocked by security policy: submit controls cannot be used for safe_expand.',
+                target,
+            };
+        }
+        if (isToggleLike(target)) {
+            return {
+                allowed: false,
+                reason: 'Blocked by security policy: toggles, checkboxes, and radio controls are not allowed.',
+                target,
+            };
+        }
+        if (DANGEROUS_RE.test(text) || MUTATING_RE.test(text)) {
+            return {
+                allowed: false,
+                reason: 'Blocked by security policy: disclosure trigger looks mutating or high-risk.',
+                target,
+            };
+        }
+        if (!isButtonLike(target) && target.tag !== 'summary' && !disclosureLike) {
+            return {
+                allowed: false,
+                reason: 'Blocked by security policy: target is not a disclosure-like control.',
+                target,
+            };
+        }
+        if (!disclosureLike && !EXPAND_TRIGGER_RE.test(text)) {
+            return {
+                allowed: false,
+                reason: 'Blocked by security policy: target does not look like a menu or disclosure trigger.',
+                target,
+            };
+        }
+        if (!labeled && !disclosureLike) {
+            return {
+                allowed: false,
+                reason: 'Blocked by security policy: unlabeled disclosure trigger is not allowed.',
+                target,
+            };
+        }
+        return { allowed: true, target };
+    }
+    return { allowed: true, target };
+}
+export function evaluateActionSecurity(action, args, context) {
+    if (action === 'navigate_to') {
+        const url = args.url;
+        if (!url)
+            return { allowed: false, reason: 'Blocked by security policy: navigation target missing.' };
+        if (!isAllowedNavigation(url, context)) {
+            return { allowed: false, reason: 'Blocked by security policy: navigation outside the allowed site scope.' };
+        }
+        if (DANGEROUS_RE.test(url) || MUTATING_RE.test(url)) {
+            return { allowed: false, reason: 'Blocked by security policy: high-risk destination URL.' };
+        }
+        return { allowed: true };
+    }
+    if (action === 'press_key') {
+        const key = String(args.key || '');
+        if (ALLOWED_KEYS.has(key))
+            return { allowed: true };
+        if (key === 'Enter' && inferAuthContext(context))
+            return { allowed: true };
+        return { allowed: false, reason: `Blocked by security policy: keyboard key "${key}" is not allowed.` };
+    }
+    if (action === 'click') {
+        const target = resolveTargetFromAction(args, context.interactiveElements);
+        if ((args.selector || (args.x !== undefined && args.y !== undefined)) && !target) {
+            return {
+                allowed: false,
+                reason: 'Blocked by security policy: unresolved selector/coordinates are not allowed. Use a known interactive element.',
+            };
+        }
+        if (!target)
+            return { allowed: true };
+        return evaluateResolvedActionSecurity(action, args, context, target);
+    }
+    if (action === 'hover') {
+        const target = resolveTargetFromAction(args, context.interactiveElements);
+        if ((args.selector || (args.x !== undefined && args.y !== undefined)) && !target) {
+            return {
+                allowed: false,
+                reason: 'Blocked by security policy: unresolved selector/coordinates are not allowed. Use a known interactive element.',
+            };
+        }
+        if (!target)
+            return { allowed: true };
+        return evaluateResolvedActionSecurity(action, args, context, target);
+    }
+    if (action === 'type_text') {
+        const target = resolveTargetFromAction(args, context.interactiveElements);
+        return evaluateResolvedActionSecurity(action, args, context, target);
+    }
+    if (action === 'select_option') {
+        const target = resolveTargetFromAction(args, context.interactiveElements);
+        return evaluateResolvedActionSecurity(action, args, context, target);
+    }
+    if (action === 'safe_expand') {
+        const target = resolveTargetFromAction(args, context.interactiveElements);
+        return evaluateResolvedActionSecurity(action, args, context, target);
+    }
+    return { allowed: true };
+}
+export function describeSecurityTarget(target) {
+    if (!target)
+        return 'target element';
+    return target.text || target.ariaLabel || target.href || target.inputType || target.tag;
+}
+//# sourceMappingURL=security.js.map

package/dist/session-profile.d.ts

@@ -0,0 +1,86 @@
+import { Browser } from './browser.js';
+import type { AgentContextEntry, AgentRunHint, LoginCredentials, SessionProfileAuthState, SessionValidationDiagnostic, SessionValidationDiagnosticConfidence, SessionProfileValidationStatus, ValidatedSessionProfile, VideoPageSignals } from './types.js';
+export interface SessionValidationResult {
+    validationStatus: Exclude<SessionProfileValidationStatus, 'repaired'>;
+    authState: SessionProfileAuthState;
+    authMatches: boolean;
+    langMatches: boolean | null;
+    themeMatches: boolean | null;
+    urlMatches: boolean;
+    authDiagnostic: SessionValidationDiagnostic;
+    langDiagnostic: SessionValidationDiagnostic;
+    themeDiagnostic: SessionValidationDiagnostic;
+    urlDiagnostic: SessionValidationDiagnostic;
+    detectedLang: string | null;
+    detectedTheme: 'light' | 'dark' | null;
+    accountLabel: string | null;
+    issues: Array<'auth' | 'lang' | 'theme' | 'url'>;
+    summary: string;
+}
+export interface RequestedLanguageState {
+    requested: string | null;
+    detected: string | null;
+    active: boolean;
+    ambiguous: boolean;
+    confidence: SessionValidationDiagnosticConfidence;
+    reasons: string[];
+}
+export interface RequestedThemeState {
+    requested: 'light' | 'dark' | null;
+    detected: 'light' | 'dark' | null;
+    active: boolean;
+    ambiguous: boolean;
+    confidence: SessionValidationDiagnosticConfidence;
+    reasons: string[];
+}
+export interface DeterministicSelectorUpdate {
+    stepSignature: string;
+    selector: string;
+    source: 'deterministic';
+    success: boolean;
+}
+export declare function evaluateRequestedLanguageState(params: {
+    currentUrl: string;
+    requestedLang?: string;
+    signals: VideoPageSignals;
+}): RequestedLanguageState;
+export declare function evaluateRequestedThemeState(params: {
+    requestedTheme?: 'light' | 'dark';
+    signals: VideoPageSignals;
+}): RequestedThemeState;
+export declare function buildAgentRunHints(entries: AgentContextEntry[]): AgentRunHint[];
+export declare function validateSessionProfile(params: {
+    currentUrl: string;
+    startUrl?: string;
+    requestedLang?: string;
+    requestedTheme?: 'light' | 'dark';
+    signals: VideoPageSignals;
+    profile?: ValidatedSessionProfile;
+}): SessionValidationResult;
+export declare function collectValidatedSessionProfile(browser: Browser, params: {
+    requestedLang?: string;
+    requestedTheme?: 'light' | 'dark';
+    startUrl?: string;
+    existingProfile?: ValidatedSessionProfile;
+    includeStorageSnapshots?: boolean;
+}): Promise<{
+    profile: ValidatedSessionProfile;
+    validation: SessionValidationResult;
+}>;
+export declare function performDeterministicSessionRepair(browser: Browser, params: {
+    startUrl?: string;
+    requestedLang?: string;
+    requestedTheme?: 'light' | 'dark';
+    credentials?: LoginCredentials;
+    profile?: ValidatedSessionProfile;
+    selectorMemory?: Record<string, string[]>;
+}): Promise<{
+    repaired: boolean;
+    validation: SessionValidationResult;
+    pathUsed: string | null;
+    updates: DeterministicSelectorUpdate[];
+}>;
+export declare function buildProfileSelectorUpdates(signals: VideoPageSignals, params: {
+    requestedLang?: string;
+    requestedTheme?: 'light' | 'dark';
+}): DeterministicSelectorUpdate[];