@qulib/core 0.4.1 → 0.4.3

package/dist/tools/auth/surface.d.ts

@@ -0,0 +1,4 @@
+import type { DetectedAuth } from '../../schemas/config.schema.js';
+import type { Gap } from '../../schemas/gap-analysis.schema.js';
+export declare function analyzeAuthSurfaceGaps(url: string, detection: DetectedAuth, timeoutMs: number): Promise<Gap[]>;
+//# sourceMappingURL=surface.d.ts.map

package/dist/tools/auth/surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../../../src/tools/auth/surface.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,sCAAsC,CAAC;AAWhE,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,YAAY,EACvB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,GAAG,EAAE,CAAC,CAwKhB"}

package/dist/tools/auth/surface.js

@@ -0,0 +1,170 @@
+import { randomUUID } from 'node:crypto';
+import { launchBrowser } from '../explorers/browser.js';
+async function waitNetworkIdleBestEffort(page) {
+    try {
+        await page.waitForLoadState('networkidle', { timeout: 5000 });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+export async function analyzeAuthSurfaceGaps(url, detection, timeoutMs) {
+    if (!detection.hasAuth) {
+        return [];
+    }
+    const gaps = [];
+    const browser = await launchBrowser();
+    try {
+        const context = await browser.newContext();
+        const page = await context.newPage();
+        const resp = await page.goto(url, { timeout: timeoutMs, waitUntil: 'domcontentloaded' }).catch(() => null);
+        if (!resp || !resp.ok()) {
+            gaps.push({
+                id: randomUUID(),
+                path: new URL(url).pathname || '/',
+                severity: 'critical',
+                category: 'auth-surface',
+                reason: 'Sign-in surface did not load successfully for evaluation.',
+                description: 'The auth entry URL failed to load or returned a non-OK status before DOM checks could run.',
+                recommendation: 'Verify DNS, TLS, and that the URL is reachable from the scan environment.',
+            });
+            return gaps;
+        }
+        await waitNetworkIdleBestEffort(page);
+        const title = await page.title().catch(() => '');
+        if (!title || title.trim().length < 3) {
+            gaps.push({
+                id: randomUUID(),
+                path: '/',
+                severity: 'medium',
+                category: 'auth-surface',
+                reason: 'Missing or trivial document title on the sign-in surface.',
+                description: 'Users and assistive tech rely on a meaningful window title.',
+                recommendation: 'Set a concise, unique <title> for the login experience.',
+            });
+        }
+        const metaDesc = await page.locator('meta[name="description"]').getAttribute('content').catch(() => null);
+        if (!metaDesc || metaDesc.trim().length < 8) {
+            gaps.push({
+                id: randomUUID(),
+                path: '/',
+                severity: 'low',
+                category: 'auth-surface',
+                reason: 'No meta description on the sign-in surface.',
+                description: 'Search and sharing previews benefit from meta description on public entry pages.',
+                recommendation: 'Add <meta name="description" content="..."> with a short summary of the product.',
+            });
+        }
+        const h1Count = await page.locator('h1').count();
+        if (h1Count === 0) {
+            gaps.push({
+                id: randomUUID(),
+                path: '/',
+                severity: 'medium',
+                category: 'auth-surface',
+                reason: 'No visible primary heading (h1) on the sign-in surface.',
+                description: 'A primary heading helps users orient on the login page.',
+                recommendation: 'Add a single descriptive <h1> for the sign-in view.',
+            });
+        }
+        const oauthButtons = page.locator('button, a[href], [role="button"]');
+        const n = await oauthButtons.count();
+        for (let i = 0; i < Math.min(n, 25); i++) {
+            const el = oauthButtons.nth(i);
+            const text = ((await el.textContent()) ?? '').trim();
+            if (!text || text.length > 120)
+                continue;
+            const isOAuthish = /google|microsoft|github|apple|sso|sign in with|log in with|continue with|oauth/i.test(text);
+            if (!isOAuthish)
+                continue;
+            const role = await el.getAttribute('role');
+            const tag = await el.evaluate((node) => node.tagName.toLowerCase());
+            const tabIndex = await el.getAttribute('tabindex');
+            const aria = await el.getAttribute('aria-label');
+            const keyboardable = tag === 'button' || tag === 'a' || role === 'button';
+            const labeled = Boolean(aria && aria.trim().length > 0) || text.length > 0;
+            if (!keyboardable || tabIndex === '-1') {
+                gaps.push({
+                    id: randomUUID(),
+                    path: '/',
+                    severity: 'high',
+                    category: 'auth-surface',
+                    reason: `OAuth control "${text.slice(0, 60)}" may not be keyboard-accessible.`,
+                    description: 'SSO entry points should be real buttons or links with focus support.',
+                    recommendation: 'Use <button> or <a href> with visible label; avoid tabindex=-1 on the only sign-in path.',
+                });
+            }
+            else if (!labeled) {
+                gaps.push({
+                    id: randomUUID(),
+                    path: '/',
+                    severity: 'medium',
+                    category: 'auth-surface',
+                    reason: `OAuth control "${text.slice(0, 60)}" lacks aria-label and has weak visible text.`,
+                    description: 'Assistive technologies need a clear accessible name for IdP buttons.',
+                    recommendation: 'Add aria-label or visible text that names the provider and action.',
+                });
+            }
+        }
+        const hasPassword = (await page.locator('input[type="password"]').count()) > 0;
+        const hasEmailLink = await page.getByText(/magic link|email.*link|passwordless/i).count();
+        const hasOAuthUi = detection.oauthButtons.length > 0 ||
+            (await page.getByText(/sign in with|continue with google|microsoft|github/i).count()) > 0;
+        const formLoginFallbacks = (detection.authOptions ?? []).filter((o) => o.type === 'form-login');
+        const hasFormLoginFallback = formLoginFallbacks.length > 0;
+        if (detection.type === 'oauth' && hasOAuthUi && !hasPassword && !hasEmailLink) {
+            if (hasFormLoginFallback) {
+                const labels = formLoginFallbacks.map((o) => o.label).join(', ');
+                gaps.push({
+                    id: randomUUID(),
+                    path: '/',
+                    severity: 'low',
+                    category: 'auth-surface',
+                    reason: `OAuth-primary login with form-login fallback detected via: ${labels}`,
+                    description: 'A form-based login path exists alongside OAuth. Automate via type="form-login" using the selectors in authOptions.',
+                    recommendation: `Automatable form option(s): ${labels}. Configure type="form-login" with credentials and selectors from detectedAuth.authOptions.`,
+                });
+            }
+            else {
+                gaps.push({
+                    id: randomUUID(),
+                    path: '/',
+                    severity: 'medium',
+                    category: 'auth-surface',
+                    reason: 'OAuth-only entry with no visible password or magic-link fallback.',
+                    description: 'Users who cannot use a social IdP need another path (email/password, help, or support).',
+                    recommendation: 'Add a documented fallback (email/password, help desk link, or alternate IdP).',
+                });
+            }
+        }
+        const errorSelectors = '[role="alert"], [data-testid*="error" i], .error, .alert-danger, [class*="error" i]';
+        const errCount = await page.locator(errorSelectors).count();
+        if (errCount === 0 && hasOAuthUi) {
+            gaps.push({
+                id: randomUUID(),
+                path: '/',
+                severity: 'low',
+                category: 'auth-surface',
+                reason: 'No obvious in-DOM error container found for OAuth sign-in failures.',
+                description: 'IdP failures should surface recoverable feedback in the page.',
+                recommendation: 'Reserve a live region or inline alert for OAuth errors returned from the provider.',
+            });
+        }
+        const help = await page.getByText(/forgot password|need help|contact support|get help/i).count();
+        if (help === 0 && hasOAuthUi) {
+            gaps.push({
+                id: randomUUID(),
+                path: '/',
+                severity: 'low',
+                category: 'auth-surface',
+                reason: 'No visible “forgot password” or help path detected near OAuth controls.',
+                description: 'Users locked out of an IdP need a support or recovery affordance.',
+                recommendation: 'Link to account recovery, IT help, or a support URL near the sign-in actions.',
+            });
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    return gaps;
+}

package/dist/tools/auth/user-providers.d.ts

@@ -0,0 +1,15 @@
+import type { OAuthProvider } from './oauth-providers.js';
+export interface SerializedProvider {
+    id: string;
+    label: string;
+    patterns: string[];
+}
+export declare function loadUserProviders(): OAuthProvider[];
+export declare function addUserProvider(input: {
+    id: string;
+    label: string;
+    pattern: string;
+}): void;
+export declare function removeUserProvider(id: string): boolean;
+export declare function listUserProviders(): SerializedProvider[];
+//# sourceMappingURL=user-providers.d.ts.map

package/dist/tools/auth/user-providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-providers.d.ts","sourceRoot":"","sources":["../../../src/tools/auth/user-providers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAgB,iBAAiB,IAAI,aAAa,EAAE,CAOnD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAc3F;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAStD;AAED,wBAAgB,iBAAiB,IAAI,kBAAkB,EAAE,CAExD"}

package/dist/tools/auth/user-providers.js

@@ -0,0 +1,62 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+const USER_PROVIDERS_PATH = join(homedir(), '.qulib', 'providers.json');
+export function loadUserProviders() {
+    const raw = loadSerialized();
+    return raw.map((p) => ({
+        id: p.id,
+        label: p.label,
+        patterns: p.patterns.map((src) => new RegExp(src, 'i')),
+    }));
+}
+export function addUserProvider(input) {
+    const existing = loadSerialized();
+    const idx = existing.findIndex((p) => p.id === input.id);
+    if (idx >= 0) {
+        const p = existing[idx];
+        if (!p.patterns.includes(input.pattern)) {
+            p.patterns.push(input.pattern);
+        }
+        p.label = input.label;
+    }
+    else {
+        existing.push({ id: input.id, label: input.label, patterns: [input.pattern] });
+    }
+    ensureDir();
+    writeFileSync(USER_PROVIDERS_PATH, JSON.stringify(existing, null, 2), 'utf-8');
+}
+export function removeUserProvider(id) {
+    const existing = loadSerialized();
+    const filtered = existing.filter((p) => p.id !== id);
+    if (filtered.length === existing.length) {
+        return false;
+    }
+    ensureDir();
+    writeFileSync(USER_PROVIDERS_PATH, JSON.stringify(filtered, null, 2), 'utf-8');
+    return true;
+}
+export function listUserProviders() {
+    return loadSerialized();
+}
+function loadSerialized() {
+    if (!existsSync(USER_PROVIDERS_PATH)) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(USER_PROVIDERS_PATH, 'utf-8'));
+        if (!Array.isArray(parsed)) {
+            return [];
+        }
+        return parsed;
+    }
+    catch {
+        return [];
+    }
+}
+function ensureDir() {
+    const dir = dirname(USER_PROVIDERS_PATH);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}

package/dist/tools/auth-block-gap.d.ts

@@ -1,3 +1,9 @@
 import type { Gap } from '../schemas/gap-analysis.schema.js';
+import type { StorageStateInvalidReason } from './auth-detector.js';
 export declare function buildAuthBlockGap(url: string): Gap;
+export declare function buildStorageStateInvalidGap(input: {
+    url: string;
+    reasonCode: StorageStateInvalidReason;
+    reason: string;
+}): Gap;
 //# sourceMappingURL=auth-block-gap.d.ts.map

package/dist/tools/auth-block-gap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-block-gap.d.ts","sourceRoot":"","sources":["../../src/tools/auth-block-gap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,mCAAmC,CAAC;AAE7D,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAiBlD"}
+{"version":3,"file":"auth-block-gap.d.ts","sourceRoot":"","sources":["../../src/tools/auth-block-gap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,mCAAmC,CAAC;AAC7D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAmBpE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAYlD;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,yBAAyB,CAAC;IACtC,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,GAAG,CAqBN"}

package/dist/tools/auth-block-gap.js

@@ -1,12 +1,23 @@
+function safeOriginAndPath(url) {
+    try {
+        const u = new URL(url);
+        return `${u.origin}${u.pathname}`;
+    }
+    catch {
+        return url;
+    }
+}
+function safeHost(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return url;
+    }
+}
 export function buildAuthBlockGap(url) {
-    const host = (() => {
-        try {
-            return new URL(url).hostname;
-        }
-        catch {
-            return url;
-        }
-    })();
+    const host = safeHost(url);
+    const safeUrl = safeOriginAndPath(url);
     return {
         id: 'auth-block',
         path: '/',
@@ -14,6 +25,28 @@ export function buildAuthBlockGap(url) {
         category: 'coverage',
         reason: `Scan blocked by authentication. No authenticated pages were evaluated for ${host}.`,
         description: 'Scan blocked by authentication. 0 authenticated pages were evaluated.',
-        recommendation: `Run \`qulib auth init --base-url ${url}\` to capture a storage state, then re-run with --auth storage-state.`,
+        recommendation: `Run \`qulib auth init --base-url ${safeUrl}\` to capture a storage state, then re-run with --auth storage-state.`,
+    };
+}
+export function buildStorageStateInvalidGap(input) {
+    const host = safeHost(input.url);
+    const safeUrl = safeOriginAndPath(input.url);
+    const recoveryByCode = {
+        'missing-file': `Storage state file was not found. Run \`qulib auth login --base-url ${safeUrl} --out <path>\` (or \`qulib auth init\`) to capture a fresh state, then re-run \`qulib analyze --url ${safeUrl} --auth-storage-state <path>\`.`,
+        'unreadable-file': `Storage state file exists but could not be read. Check file permissions, then re-run \`qulib auth login\` if needed.`,
+        'invalid-json': `Storage state file is not valid JSON. Run \`qulib auth login --base-url ${safeUrl} --out <path>\` again to regenerate it.`,
+        'wrong-origin': `Storage state belongs to a different origin than ${host}. Re-run \`qulib auth login --base-url ${safeUrl}\` against this target and pass the new file to \`qulib analyze\`.`,
+        'expired-or-unauthorized': `The session in the storage state has expired or is unauthorized. Run \`qulib auth login --base-url ${safeUrl}\` to capture a fresh state, then re-run \`qulib analyze --url ${safeUrl} --auth-storage-state <path>\`.`,
+        'no-auth-cookies': `Storage state file contains no cookies or localStorage entries — it is effectively empty. Run \`qulib auth login --base-url ${safeUrl}\` to capture a real session.`,
+        unknown: `Storage state could not be validated. Try \`qulib auth login --base-url ${safeUrl}\` again, and verify the file was saved on the same origin.`,
+    };
+    return {
+        id: 'storage-state-invalid',
+        path: '/',
+        severity: 'critical',
+        category: 'coverage',
+        reason: `Authenticated scan could not continue because the provided storage state is invalid for ${host}. Reason: ${input.reasonCode} — ${input.reason}.`,
+        description: `Storage state validation failed before crawling. The session was checked against ${host} and rejected with reason code "${input.reasonCode}".`,
+        recommendation: recoveryByCode[input.reasonCode],
     };
 }

package/dist/tools/auth-detector.d.ts

@@ -1,4 +1,23 @@
+import type { Page } from '@playwright/test';
 import type { DetectedAuth } from '../schemas/config.schema.js';
 import type { AnalyzeProgressSink } from '../harness/progress-log.js';
+export type StorageStateInvalidReason = 'missing-file' | 'unreadable-file' | 'invalid-json' | 'wrong-origin' | 'expired-or-unauthorized' | 'no-auth-cookies' | 'unknown';
+export interface StorageStateValidationResult {
+    valid: boolean;
+    reasonCode: StorageStateInvalidReason | 'ok';
+    reason: string;
+}
+export declare function evaluateStorageStateValidity(signals: {
+    expectedOrigin: string;
+    finalUrl: string;
+    visiblePasswordCount: number;
+    hadUnauthorizedHttp: boolean;
+}): StorageStateValidationResult;
+export declare function preflightStorageStateFile(storagePath: string): Promise<StorageStateValidationResult | null>;
+export declare function waitForReturnToOrigin(page: Page, baseUrl: string, timeoutMs?: number): Promise<{
+    returned: boolean;
+    finalUrl: string;
+}>;
+export declare function validateStorageState(url: string, storagePath: string, timeoutMs?: number): Promise<StorageStateValidationResult>;
 export declare function detectAuth(url: string, timeoutMs?: number, progress?: AnalyzeProgressSink): Promise<DetectedAuth>;
 //# sourceMappingURL=auth-detector.d.ts.map

package/dist/tools/auth-detector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-detector.d.ts","sourceRoot":"","sources":["../../src/tools/auth-detector.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAY,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAsPtE,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,SAAQ,EACjB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,YAAY,CAAC,CAkJvB"}
+{"version":3,"file":"auth-detector.d.ts","sourceRoot":"","sources":["../../src/tools/auth-detector.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAY,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAItE,MAAM,MAAM,yBAAyB,GACjC,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,cAAc,GACd,yBAAyB,GACzB,iBAAiB,GACjB,SAAS,CAAC;AAEd,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB;AAsQD,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACpD,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;CAC9B,GAAG,4BAA4B,CA6B/B;AAOD,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,4BAA4B,GAAG,IAAI,CAAC,CAgD9C;AAED,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,SAAS,SAAQ,GAChB,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAelD;AAED,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,SAAS,SAAQ,GAChB,OAAO,CAAC,4BAA4B,CAAC,CAyDvC;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,SAAQ,EACjB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,YAAY,CAAC,CAqJvB"}

package/dist/tools/auth-detector.js

@@ -1,3 +1,5 @@
+import { resolve } from 'node:path';
+import { readFile, stat } from 'node:fs/promises';
 import { launchBrowser } from './browser.js';
 import { BUILT_IN_OAUTH_PROVIDERS } from './oauth-providers.js';
 async function waitNetworkIdleBestEffort(page) {
@@ -166,6 +168,7 @@ async function probeClickToRevealForms(page, loginUrl, alreadyMatchedTexts, time
             continue;
         seenLabels.add(label);
         candidateAttempts += 1;
+        const originBefore = new URL(page.url()).origin;
         if (debugAuth()) {
             progress?.debug(`detect_auth click-reveal try label="${label.slice(0, 80)}"`);
         }
@@ -191,7 +194,21 @@ async function probeClickToRevealForms(page, loginUrl, alreadyMatchedTexts, time
             continue;
         }
         try {
-            await page.locator('input[type="password"]').first().waitFor({ state: 'visible', timeout: 2000 });
+            await page.waitForLoadState('domcontentloaded', { timeout: 5000 });
+        }
+        catch {
+            /* best-effort after navigation */
+        }
+        if (new URL(page.url()).origin !== originBefore) {
+            if (debugAuth()) {
+                progress?.debug(`detect_auth click-reveal aborted (cross-origin after click): was ${originBefore} now ${new URL(page.url()).origin}`);
+            }
+            await page.goto(loginUrl, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
+            await waitNetworkIdleBestEffort(page);
+            continue;
+        }
+        try {
+            await page.locator('input[type="password"]:visible').first().waitFor({ state: 'visible', timeout: 2000 });
         }
         catch {
             await page.goto(loginUrl, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
@@ -218,6 +235,161 @@ async function probeClickToRevealForms(page, loginUrl, alreadyMatchedTexts, time
     }
     return out;
 }
+export function evaluateStorageStateValidity(signals) {
+    let finalOrigin = null;
+    try {
+        finalOrigin = new URL(signals.finalUrl).origin;
+    }
+    catch {
+        finalOrigin = null;
+    }
+    if (finalOrigin === null || finalOrigin !== signals.expectedOrigin) {
+        return {
+            valid: false,
+            reasonCode: 'wrong-origin',
+            reason: 'session redirected to a different origin than the target app',
+        };
+    }
+    if (signals.visiblePasswordCount > 0) {
+        return {
+            valid: false,
+            reasonCode: 'expired-or-unauthorized',
+            reason: 'login form still visible after loading storage state (session likely expired)',
+        };
+    }
+    if (signals.hadUnauthorizedHttp) {
+        return {
+            valid: false,
+            reasonCode: 'expired-or-unauthorized',
+            reason: 'HTTP 401/403 on authenticated request (session likely expired or invalid)',
+        };
+    }
+    return { valid: true, reasonCode: 'ok', reason: 'session appears active' };
+}
+export async function preflightStorageStateFile(storagePath) {
+    let exists = false;
+    try {
+        const s = await stat(storagePath);
+        exists = s.isFile();
+    }
+    catch {
+        exists = false;
+    }
+    if (!exists) {
+        return {
+            valid: false,
+            reasonCode: 'missing-file',
+            reason: 'storage state file does not exist',
+        };
+    }
+    let raw;
+    try {
+        raw = await readFile(storagePath, 'utf8');
+    }
+    catch {
+        return {
+            valid: false,
+            reasonCode: 'unreadable-file',
+            reason: 'storage state file is not readable',
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            valid: false,
+            reasonCode: 'invalid-json',
+            reason: 'storage state file is not valid JSON',
+        };
+    }
+    const cookieCount = Array.isArray(parsed?.cookies) ? parsed.cookies.length : 0;
+    const originEntries = Array.isArray(parsed?.origins) ? parsed.origins : [];
+    const localStorageEntryCount = originEntries.reduce((sum, entry) => {
+        return sum + (Array.isArray(entry?.localStorage) ? entry.localStorage.length : 0);
+    }, 0);
+    if (cookieCount === 0 && localStorageEntryCount === 0) {
+        return {
+            valid: false,
+            reasonCode: 'no-auth-cookies',
+            reason: 'storage state file contains no cookies and no localStorage entries',
+        };
+    }
+    return null;
+}
+export async function waitForReturnToOrigin(page, baseUrl, timeoutMs = 15000) {
+    const targetOrigin = new URL(baseUrl).origin;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const finalUrl = page.url();
+        try {
+            if (new URL(finalUrl).origin === targetOrigin) {
+                return { returned: true, finalUrl };
+            }
+        }
+        catch {
+            /* ignore transient invalid URLs */
+        }
+        await new Promise((r) => setTimeout(r, 500));
+    }
+    return { returned: false, finalUrl: page.url() };
+}
+export async function validateStorageState(url, storagePath, timeoutMs = 10000) {
+    let expectedOrigin;
+    try {
+        expectedOrigin = new URL(url).origin;
+    }
+    catch {
+        return {
+            valid: false,
+            reasonCode: 'unknown',
+            reason: 'target URL could not be parsed for origin matching',
+        };
+    }
+    const storageAbs = resolve(process.cwd(), storagePath);
+    const preflight = await preflightStorageStateFile(storageAbs);
+    if (preflight !== null) {
+        return preflight;
+    }
+    let hadUnauthorizedHttp = false;
+    const browser = await launchBrowser();
+    try {
+        const context = await browser.newContext({ storageState: storageAbs });
+        const page = await context.newPage();
+        page.on('response', (res) => {
+            const s = res.status();
+            if (s === 401 || s === 403) {
+                hadUnauthorizedHttp = true;
+            }
+        });
+        try {
+            await page.goto(url, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
+        }
+        catch {
+            return {
+                valid: false,
+                reasonCode: 'unknown',
+                reason: 'navigation to target URL failed while validating storage state',
+            };
+        }
+        await waitNetworkIdleBestEffort(page);
+        const finalUrl = page.url();
+        const visiblePasswordCount = await page
+            .locator('input[type="password"]:visible')
+            .count()
+            .catch(() => 0);
+        return evaluateStorageStateValidity({
+            expectedOrigin,
+            finalUrl,
+            visiblePasswordCount,
+            hadUnauthorizedHttp,
+        });
+    }
+    finally {
+        await browser.close();
+    }
+}
 export async function detectAuth(url, timeoutMs = 15000, progress) {
     const browser = await launchBrowser();
     try {
@@ -232,7 +404,7 @@ export async function detectAuth(url, timeoutMs = 15000, progress) {
         }
         let loginUrl = url;
         const looksLikeLoginPage = /login|sign[- ]?in|auth/i.test(page.url()) ||
-            (await page.locator('input[type="password"]').count()) > 0;
+            (await page.locator('input[type="password"]:visible').count()) > 0;
         if (!looksLikeLoginPage) {
             const loginLink = page.locator('a').filter({ hasText: /^(log ?in|sign ?in|sign in)$/i }).first();
             const loginLinkCount = await loginLink.count();
@@ -247,7 +419,7 @@ export async function detectAuth(url, timeoutMs = 15000, progress) {
                 }
             }
         }
-        const passwordInputs = page.locator('input[type="password"]');
+        const passwordInputs = page.locator('input[type="password"]:visible');
         const passwordCount = await passwordInputs.count();
         progress?.debug(`detect_auth selector input[type=password] count=${passwordCount}`);
         const hasFormLogin = passwordCount > 0;
@@ -274,13 +446,19 @@ export async function detectAuth(url, timeoutMs = 15000, progress) {
                     matchedAny = true;
                 }
             }
-            // Capture unrecognized SSO-like buttons so they appear in the result
-            if (!matchedAny && !oauthButtons.find((b) => b.text === trimmed.slice(0, 100))) {
-                oauthButtons.push({ provider: 'unknown', text: trimmed.slice(0, 100) });
+            if (!matchedAny) {
+                const builtIn = BUILT_IN_OAUTH_PROVIDERS.find((p) => p.label.toLowerCase() === trimmed.toLowerCase());
+                if (builtIn) {
+                    if (!oauthButtons.find((b) => b.provider === builtIn.id)) {
+                        oauthButtons.push({ provider: builtIn.id, text: trimmed.slice(0, 100) });
+                    }
+                }
+                else if (!oauthButtons.find((b) => b.text === trimmed.slice(0, 100))) {
+                    oauthButtons.push({ provider: 'unknown', text: trimmed.slice(0, 100) });
+                }
             }
         }
-        // Only skip buttons already tied to a built-in IdP — leave `unknown` labels probe-able for click-to-reveal forms.
-        const skipProbeLabels = new Set(oauthButtons.filter((b) => b.provider !== 'unknown').map((b) => b.text.trim()));
+        const skipProbeLabels = new Set(oauthButtons.map((b) => b.text.trim()));
         const clickRevealForms = await probeClickToRevealForms(page, loginUrl, skipProbeLabels, timeoutMs, progress);
         const pageText = await page.locator('body').innerText().catch(() => '');
         const hasMagicLink = MAGIC_LINK_PATTERNS.some((p) => p.test(pageText));

package/dist/tools/automation-maturity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"automation-maturity.d.ts","sourceRoot":"","sources":["../../src/tools/automation-maturity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAA+B,MAAM,0CAA0C,CAAC;AAiDhH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,YAAY,GAAG,kBAAkB,CA6HhF"}
+{"version":3,"file":"automation-maturity.d.ts","sourceRoot":"","sources":["../../src/tools/automation-maturity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EACV,kBAAkB,EAGnB,MAAM,0CAA0C,CAAC;AAiDlD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,YAAY,GAAG,kBAAkB,CAuLhF"}