@sovovs/bycli 1.8.0 → 2.0.0

package/cli-manifest.json

@@ -14863,67 +14863,6 @@
     "modulePath": "jira/search.js",
     "sourceFile": "jira/search.js"
   },
-  {
-    "site": "juejin",
-    "name": "search",
-    "description": "掘金搜索",
-    "access": "read",
-    "domain": "juejin.cn",
-    "strategy": "public",
-    "browser": true,
-    "args": [
-      {
-        "name": "query",
-        "type": "str",
-        "required": true,
-        "positional": true,
-        "help": "搜索关键词"
-      },
-      {
-        "name": "limit",
-        "type": "int",
-        "default": 10,
-        "required": false,
-        "help": "返回结果数量 (max 20)"
-      },
-      {
-        "name": "type",
-        "type": "int",
-        "default": 0,
-        "required": false,
-        "help": "搜索类型：0=综合搜索，2=文章搜索，12=课程搜索，9=标签搜索，1=用户搜索",
-        "choices": [
-          "0",
-          "2",
-          "12",
-          "9",
-          "1"
-        ]
-      },
-      {
-        "name": "sort",
-        "type": "int",
-        "default": 0,
-        "required": false,
-        "help": "排序类型：0=综合排序，1=最新优先，2=最热优先",
-        "choices": [
-          "0",
-          "1",
-          "2"
-        ]
-      }
-    ],
-    "columns": [
-      "rank",
-      "title",
-      "author",
-      "summary",
-      "url"
-    ],
-    "type": "js",
-    "modulePath": "juejin/search.js",
-    "sourceFile": "juejin/search.js"
-  },
   {
     "site": "ke",
     "name": "chengjiao",

package/dist/src/adapter-shadow.js

@@ -1,6 +1,6 @@
 import * as fs from 'node:fs';
-import * as os from 'node:os';
 import * as path from 'node:path';
+import { getUserClisDir } from './config-paths.js';
 import { fileURLToPath } from 'node:url';
 import { findPackageRoot, getCliManifestPath } from './package-paths.js';
 function defaultBuiltinClisDir() {
@@ -31,7 +31,7 @@ function loadBuiltinCommandFiles(builtinClisDir) {
     }
 }
 export function findShadowedUserAdapters(opts = {}) {
-    const userClisDir = opts.userClisDir ?? path.join(os.homedir(), '.bycli', 'clis');
+    const userClisDir = opts.userClisDir ?? getUserClisDir();
     const builtinClisDir = opts.builtinClisDir ?? defaultBuiltinClisDir();
     const builtinCommandFiles = loadBuiltinCommandFiles(builtinClisDir);
     const shadows = [];

package/dist/src/browser/analyze.d.ts

@@ -1,103 +1,14 @@
 /**
- * `browser analyze <url>` — turn site-recon guesswork into deterministic CLI output.
+ * `browser analyze <url>` — site-recon classification.
  *
- * When an agent starts a new adapter, the first question is "which pattern am
- * I looking at?" (A/B/C/D/E from site-recon docs) and "will Node-side fetch
- * work, or will anti-bot middleware block me?". Today the agent has to open
- * the page, poke `network`, try cURL, fail, guess again. This module condenses
- * that into one call that returns a classification + evidence.
+ * The pure analysis logic moved to the shared package `@sovovs/bycli-recorder-core`
+ * (M5a, same pure-domain split as rank/M4) so dashboard-be can reuse it too. This
+ * module re-exports it so existing main-repo importers (cli.ts, the high-level
+ * analyze module) are unchanged. The CLI wrapper drives a real page, feeds the
+ * resulting PageSignals here, and prints the verdict.
  *
- * Kept pure (no page imports) so the bulk is unit-testable; the CLI wrapper
- * drives a real page, feeds the resulting signals here, and prints the verdict.
+ * Note: the package types the registry as a structural `AdapterRef` ({site,name,
+ * domain?}); the main-repo `CliCommand` is assignable to it, so callers can keep
+ * passing `getRegistry()` (Map<string, CliCommand>) unchanged.
  */
-import type { CliCommand } from '../registry.js';
-export interface PageSignals {
-    /** URL we navigated to (may redirect; both fields help agents notice that). */
-    requestedUrl: string;
-    finalUrl: string;
-    /** document.cookie split into names; value not needed for detection. */
-    cookieNames: string[];
-    /**
-     * Response bodies captured during the navigation + first few seconds.
-     * We only need enough body text to spot WAF markers; the CLI truncates
-     * per-entry before feeding us.
-     */
-    networkEntries: Array<{
-        url: string;
-        status: number;
-        contentType: string;
-        /** First N chars of body; null when not available. */
-        bodyPreview: string | null;
-    }>;
-    /**
-     * Which globals the page exposes on `window`. We don't care about the values,
-     * just presence — distinguishes Pattern B (SSR state) from Pattern A.
-     */
-    initialState: {
-        __INITIAL_STATE__: boolean;
-        __NUXT__: boolean;
-        __NEXT_DATA__: boolean;
-        __APOLLO_STATE__: boolean;
-    };
-    /** Document title — only for the human-debug `summary` field. */
-    title: string;
-}
-export type AntiBotVendor = 'aliyun_waf' | 'cloudflare' | 'akamai' | 'geetest' | 'unknown';
-export interface AntiBotVerdict {
-    detected: boolean;
-    vendor: AntiBotVendor | null;
-    evidence: string[];
-    /** One-line imperative instruction for the agent. */
-    implication: string;
-}
-export declare function detectAntiBot(signals: PageSignals): AntiBotVerdict;
-export type Pattern = 'A' | 'B' | 'C' | 'D' | 'E' | 'unknown';
-export interface PatternVerdict {
-    pattern: Pattern;
-    reason: string;
-    /** How many JSON XHR/fetch responses we saw during navigation. */
-    json_responses: number;
-    /** Count of non-2xx API responses — hint for token-gated (Pattern D). */
-    auth_failures: number;
-}
-/**
- * Apply the decision tree from `site-recon.md` mechanically.
- *
- * B beats A when initial-state globals are present: even if the page fetches
- * more data via XHR afterwards, the SSR payload is the highest-leverage source.
- * D (token-gated) dominates when we see 401/403 on what looks like API
- * endpoints — without that, an authenticated route looks identical to A.
- */
-export declare function classifyPattern(signals: PageSignals): PatternVerdict;
-export interface NearestAdapter {
-    site: string;
-    example_commands: string[];
-    reason: string;
-}
-/**
- * Find existing adapters that target the same site.
- *
- * Keep the hostname match simple — agents extend naming conventions
- * differently per site, so we match on the registered `domain` field and fall
- * back to site-name containment. Returning `null` is fine; agents can always
- * read site-memory docs.
- */
-export declare function findNearestAdapter(finalUrl: string, registry: Map<string, CliCommand>): NearestAdapter | null;
-export interface AnalyzeReport {
-    requested_url: string;
-    final_url: string;
-    title: string;
-    pattern: PatternVerdict;
-    anti_bot: AntiBotVerdict;
-    initial_state: PageSignals['initialState'];
-    nearest_adapter: NearestAdapter | null;
-    recommended_next_step: string;
-}
-/**
- * Synthesize the verdict from collected signals + registry.
- *
- * The `recommended_next_step` is deliberately a single imperative
- * sentence — agents act on it directly instead of re-deriving advice from
- * the structured fields.
- */
-export declare function analyzeSite(signals: PageSignals, registry: Map<string, CliCommand>): AnalyzeReport;
+export { analyzeSite, detectAntiBot, classifyPattern, findNearestAdapter, type AdapterRef, type PageSignals, type AnalyzeReport, type AntiBotVerdict, type AntiBotVendor, type PatternVerdict, type Pattern, type NearestAdapter, } from '@sovovs/bycli-recorder-core';

package/dist/src/browser/analyze.js

@@ -1,230 +1,14 @@
 /**
- * `browser analyze <url>` — turn site-recon guesswork into deterministic CLI output.
+ * `browser analyze <url>` — site-recon classification.
  *
- * When an agent starts a new adapter, the first question is "which pattern am
- * I looking at?" (A/B/C/D/E from site-recon docs) and "will Node-side fetch
- * work, or will anti-bot middleware block me?". Today the agent has to open
- * the page, poke `network`, try cURL, fail, guess again. This module condenses
- * that into one call that returns a classification + evidence.
+ * The pure analysis logic moved to the shared package `@sovovs/bycli-recorder-core`
+ * (M5a, same pure-domain split as rank/M4) so dashboard-be can reuse it too. This
+ * module re-exports it so existing main-repo importers (cli.ts, the high-level
+ * analyze module) are unchanged. The CLI wrapper drives a real page, feeds the
+ * resulting PageSignals here, and prints the verdict.
  *
- * Kept pure (no page imports) so the bulk is unit-testable; the CLI wrapper
- * drives a real page, feeds the resulting signals here, and prints the verdict.
+ * Note: the package types the registry as a structural `AdapterRef` ({site,name,
+ * domain?}); the main-repo `CliCommand` is assignable to it, so callers can keep
+ * passing `getRegistry()` (Map<string, CliCommand>) unchanged.
  */
-/**
- * WAF vendors we can reliably detect from cookies + response body markers
- * alone. Signals are orthogonal per vendor — so when two vendors match
- * simultaneously (rare), we keep all evidence and report the higher-signal
- * vendor first.
- */
-const WAF_SIGNATURES = [
-    {
-        vendor: 'aliyun_waf',
-        cookiePatterns: [/^acw_sc__v2$/, /^acw_tc$/, /^ssxmod_itna/],
-        bodyPatterns: [/arg1\s*=\s*['"][0-9A-F]{30,}/, /\/ntc_captcha\//i],
-        implication: 'Direct Node-side fetch/curl will return the slider HTML. Validate the endpoint in browser context first; HTML COOKIE adapters still finish with Node-side fetch + page.getCookies.',
-    },
-    {
-        vendor: 'cloudflare',
-        cookiePatterns: [/^__cf_bm$/, /^cf_clearance$/, /^__cfduid$/],
-        bodyPatterns: [/Cloudflare Ray ID/i, /Checking your browser before accessing/i, /cf-chl-/i],
-        implication: 'Cloudflare bot check. Start from a real browser session; probe in browser context first. HTML COOKIE adapters still finish with Node-side fetch + page.getCookies.',
-    },
-    {
-        vendor: 'akamai',
-        cookiePatterns: [/^_abck$/, /^bm_sz$/, /^bm_sv$/],
-        bodyPatterns: [/akamai/i],
-        implication: 'Akamai Bot Manager. Probe in browser context first; keep final HTML COOKIE adapters on Node-side fetch + page.getCookies.',
-    },
-    {
-        vendor: 'geetest',
-        cookiePatterns: [],
-        bodyPatterns: [/geetest/i, /gt_captcha/i],
-        implication: 'Geetest slider/puzzle captcha. Agent cannot bypass programmatically — requires UI strategy or human-in-loop.',
-    },
-];
-export function detectAntiBot(signals) {
-    const evidence = [];
-    let match = null;
-    for (const sig of WAF_SIGNATURES) {
-        const hits = [];
-        for (const pat of sig.cookiePatterns) {
-            const hit = signals.cookieNames.find((c) => pat.test(c));
-            if (hit)
-                hits.push(`cookie:${hit}`);
-        }
-        for (const pat of sig.bodyPatterns) {
-            for (const entry of signals.networkEntries) {
-                if (entry.bodyPreview && pat.test(entry.bodyPreview)) {
-                    hits.push(`body:${entry.url}`);
-                    break;
-                }
-            }
-        }
-        if (hits.length > 0 && !match) {
-            match = sig;
-            evidence.push(...hits);
-        }
-    }
-    if (!match) {
-        return {
-            detected: false,
-            vendor: null,
-            evidence: [],
-            implication: 'No known anti-bot signatures. Try Node-side COOKIE fetch first; if endpoint validation is blocked, retry from browser context.',
-        };
-    }
-    return {
-        detected: true,
-        vendor: match.vendor,
-        evidence,
-        implication: match.implication,
-    };
-}
-/**
- * Apply the decision tree from `site-recon.md` mechanically.
- *
- * B beats A when initial-state globals are present: even if the page fetches
- * more data via XHR afterwards, the SSR payload is the highest-leverage source.
- * D (token-gated) dominates when we see 401/403 on what looks like API
- * endpoints — without that, an authenticated route looks identical to A.
- */
-export function classifyPattern(signals) {
-    const jsonEntries = signals.networkEntries.filter((e) => /json/i.test(e.contentType));
-    const authFailures = signals.networkEntries.filter((e) => e.status === 401 || e.status === 403).length;
-    const hasInitialState = signals.initialState.__INITIAL_STATE__ ||
-        signals.initialState.__NUXT__ ||
-        signals.initialState.__NEXT_DATA__ ||
-        signals.initialState.__APOLLO_STATE__;
-    if (authFailures >= 2 && jsonEntries.length >= 1) {
-        return {
-            pattern: 'D',
-            reason: `${authFailures} auth-failing API responses seen — endpoint is token-gated`,
-            json_responses: jsonEntries.length,
-            auth_failures: authFailures,
-        };
-    }
-    if (hasInitialState) {
-        const which = Object.entries(signals.initialState)
-            .filter(([, v]) => v)
-            .map(([k]) => k);
-        return {
-            pattern: 'B',
-            reason: `SSR state global present: ${which.join(', ')}`,
-            json_responses: jsonEntries.length,
-            auth_failures: authFailures,
-        };
-    }
-    if (jsonEntries.length >= 1) {
-        return {
-            pattern: 'A',
-            reason: `${jsonEntries.length} JSON XHR/fetch responses observed — classic API pattern`,
-            json_responses: jsonEntries.length,
-            auth_failures: authFailures,
-        };
-    }
-    // No API, no SSR state — probably static HTML or a bundled SPA that lazy-loads.
-    // Pattern C (HTML scrape) is the default fallback; E (streaming) we can't
-    // reliably detect without watching WebSocket frames, so we label 'C' and
-    // leave the agent to upgrade to E manually if they see WS traffic.
-    return {
-        pattern: 'C',
-        reason: 'No JSON XHR and no SSR state — HTML scrape (Pattern C); escalate to E manually if WebSocket traffic appears',
-        json_responses: jsonEntries.length,
-        auth_failures: authFailures,
-    };
-}
-/**
- * Find existing adapters that target the same site.
- *
- * Keep the hostname match simple — agents extend naming conventions
- * differently per site, so we match on the registered `domain` field and fall
- * back to site-name containment. Returning `null` is fine; agents can always
- * read site-memory docs.
- */
-export function findNearestAdapter(finalUrl, registry) {
-    let host;
-    try {
-        host = new URL(finalUrl).hostname;
-    }
-    catch {
-        return null;
-    }
-    // Strip leading www.; 'www' as a site identifier is never what an adapter uses.
-    const cleanedHost = host.replace(/^www\./, '');
-    // Extract apex (xx.com) and registrable parts for fuzzy match.
-    const parts = cleanedHost.split('.');
-    const apex = parts.slice(-2).join('.');
-    const siteKey = parts.length > 1 ? parts[parts.length - 2] : cleanedHost;
-    const hits = new Map();
-    for (const cmd of registry.values()) {
-        const domain = cmd.domain?.toLowerCase();
-        const siteMatches = (domain && (cleanedHost.endsWith(domain) || domain.endsWith(apex))) ||
-            cmd.site.toLowerCase() === siteKey?.toLowerCase() ||
-            cleanedHost.includes(cmd.site.toLowerCase());
-        if (siteMatches) {
-            const list = hits.get(cmd.site) ?? [];
-            list.push(cmd);
-            hits.set(cmd.site, list);
-        }
-    }
-    if (hits.size === 0)
-        return null;
-    // Pick the site with the most commands — likely the most-developed adapter,
-    // and the best reference for a new command on the same host.
-    let best = null;
-    for (const entry of hits) {
-        if (!best || entry[1].length > best[1].length)
-            best = entry;
-    }
-    if (!best)
-        return null;
-    return {
-        site: best[0],
-        example_commands: best[1].slice(0, 5).map((c) => `${c.site} ${c.name}`),
-        reason: `${best[1].length} existing adapter${best[1].length === 1 ? '' : 's'} target this site — reuse strategy/cookie config`,
-    };
-}
-/**
- * Synthesize the verdict from collected signals + registry.
- *
- * The `recommended_next_step` is deliberately a single imperative
- * sentence — agents act on it directly instead of re-deriving advice from
- * the structured fields.
- */
-export function analyzeSite(signals, registry) {
-    const pattern = classifyPattern(signals);
-    const antiBot = detectAntiBot(signals);
-    const nearest = findNearestAdapter(signals.finalUrl, registry);
-    let next;
-    if (antiBot.detected) {
-        next = antiBot.implication;
-    }
-    else if (pattern.pattern === 'A') {
-        next = 'Pick the most specific JSON endpoint from `bycli browser network` and try a bare Node fetch with cookies; escalate to browser-context fetch only if blocked.';
-    }
-    else if (pattern.pattern === 'B') {
-        next = 'Read the SSR global via `bycli browser eval "JSON.stringify(window.__INITIAL_STATE__ ?? window.__NUXT__ ?? window.__NEXT_DATA__ ?? window.__APOLLO_STATE__)"` — no API needed.';
-    }
-    else if (pattern.pattern === 'C') {
-        next = 'No API visible — use SSR HTML scrape (e.g. `bycli browser extract`) against the rendered page.';
-    }
-    else if (pattern.pattern === 'D') {
-        next = 'Endpoints need auth. Re-open the page from a signed-in session, then retry analyze; see `field-decode-playbook` §4 for token tracing.';
-    }
-    else if (pattern.pattern === 'E') {
-        next = 'WebSocket stream detected — find the underlying HTTP poll/long-poll endpoint; raw WS is not supported.';
-    }
-    else {
-        next = 'No strong signal. Manually inspect `bycli browser network --all` and pick a pattern.';
-    }
-    return {
-        requested_url: signals.requestedUrl,
-        final_url: signals.finalUrl,
-        title: signals.title,
-        pattern,
-        anti_bot: antiBot,
-        initial_state: signals.initialState,
-        nearest_adapter: nearest,
-        recommended_next_step: next,
-    };
-}
+export { analyzeSite, detectAntiBot, classifyPattern, findNearestAdapter, } from '@sovovs/bycli-recorder-core';

package/dist/src/browser/cdp.js

@@ -13,9 +13,36 @@ import { request as httpsRequest } from 'node:https';
 import { buildEvaluateExpression } from './utils.js';
 import { generateStealthJs } from './stealth.js';
 import { waitForDomStableJs } from './dom-helpers.js';
+import { armNavigationGuard, NavigationBlockedError } from './navigation-guard.js';
+import { checkUrlPolicy } from './url-policy.js';
 import { isRecord, saveBase64ToFile } from '../utils.js';
 import { getAllElectronApps } from '../electron-apps.js';
 import { BasePage } from './base-page.js';
+/** Lazily-built DnsResolver backed by node:dns/promises (for guarded navigation). */
+let _dnsResolver;
+function getDefaultDnsResolver() {
+    if (_dnsResolver)
+        return _dnsResolver;
+    // Imported lazily so the module stays usable in environments without node:dns.
+    const dns = require('node:dns').promises;
+    _dnsResolver = {
+        resolve4: (h) => dns.resolve4(h),
+        resolve6: (h) => dns.resolve6(h),
+    };
+    return _dnsResolver;
+}
+/** Resolve once the guard records a blocked main-frame request (polled). */
+function waitForBlocked(guard, intervalMs = 100, timeoutMs = 30_000) {
+    return new Promise((resolve) => {
+        const start = Date.now();
+        const timer = setInterval(() => {
+            if (guard.blocked.length > 0 || Date.now() - start > timeoutMs) {
+                clearInterval(timer);
+                resolve();
+            }
+        }, intervalMs);
+    });
+}
 const CDP_SEND_TIMEOUT = 30_000;
 // Memory guard for in-process capture. The 4k cap we used to apply everywhere
 // silently truncated JSON so `JSON.parse` failed or gave partial objects — the
@@ -172,13 +199,43 @@ class CDPPage extends BasePage {
             await this.bridge.send('Page.enable');
             this._pageEnabled = true;
         }
-        const loadPromise = this.bridge.waitForEvent('Page.loadEventFired', 30_000).catch(() => { });
-        await this.bridge.send('Page.navigate', { url });
-        await loadPromise;
-        this._lastUrl = url;
-        if (options?.waitUntil !== 'none') {
-            const maxMs = options?.settleMs ?? 1000;
-            await this.evaluate(waitForDomStableJs(maxMs, Math.min(500, maxMs)));
+        // Opt-in guarded navigation (M1 P0-1, direct-CDP side). Only the recorder path
+        // sets guardNavigation; general automation (incl. localhost fixtures) is
+        // unchanged. Pre-checks the target (syntax + DNS) and arms Fetch before-send
+        // interception before Page.navigate, so redirects to forbidden targets are
+        // failRequest'd before send. ip-observed-only per ADR-0006.
+        let guard;
+        if (options?.guardNavigation) {
+            const resolver = getDefaultDnsResolver();
+            const pre = await checkUrlPolicy(url, resolver);
+            if (!pre.ok) {
+                throw new NavigationBlockedError(url, pre.reason, pre.detail);
+            }
+            guard = await armNavigationGuard(this.bridge, resolver, { observeIp: true });
+        }
+        try {
+            const loadPromise = this.bridge.waitForEvent('Page.loadEventFired', 30_000).catch(() => { });
+            await this.bridge.send('Page.navigate', { url });
+            if (guard) {
+                // A blocked main-frame request never fires loadEventFired — race the load
+                // against a short poll of the guard's blocked list so we don't wait 30s.
+                await Promise.race([loadPromise, waitForBlocked(guard)]);
+                if (guard.blocked.length > 0) {
+                    throw new NavigationBlockedError(url, 'forbidden_ip', `redirect blocked: ${guard.blocked.map((b) => b.url).join(', ')}`);
+                }
+            }
+            else {
+                await loadPromise;
+            }
+            this._lastUrl = url;
+            if (options?.waitUntil !== 'none') {
+                const maxMs = options?.settleMs ?? 1000;
+                await this.evaluate(waitForDomStableJs(maxMs, Math.min(500, maxMs)));
+            }
+        }
+        finally {
+            if (guard)
+                await guard.dispose();
         }
     }
     async evaluate(input, ...args) {

package/dist/src/browser/navigation-guard.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Navigation interception guard (M1 spike, direct-CDP / Node side).
+ *
+ * Closes the P0 hole where navigation fired before request interception was armed.
+ * The contract (ADR-0002, ADR-0006, 04-security-model.md) is:
+ *
+ *   1. Pre-check the target URL (syntax + DNS precheck) BEFORE any navigation.
+ *   2. Arm Fetch interception (resourceType Document, Request stage) and confirm the
+ *      handler is registered BEFORE the single Page.navigate.
+ *   3. Re-run the full URL policy on every paused main-frame Document request
+ *      (initial + every redirect / secondary main-frame request) and failRequest
+ *      anything that does not pass — so a forbidden redirect target receives 0 bytes.
+ *   4. If interception cannot be armed, FAIL CLOSED — never fall back to bare
+ *      navigation. Callers surface `navigation_redirect_requires_interception`.
+ *
+ * remoteIPAddress observed on Network.responseReceived is logged only — it is
+ * post-connect and therefore `ip-observed-only`, NOT a security boundary (ADR-0006).
+ *
+ * This module is runtime-bound only through the small InterceptBridge interface,
+ * so it is unit-testable with a fake bridge (no real CDP / network).
+ */
+import { type DnsResolver, type UrlPolicyReason } from './url-policy.js';
+/** Minimal CDP surface this guard needs (satisfied by CDPBridge). */
+export interface InterceptBridge {
+    send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    on(event: string, handler: (params: unknown) => void): void;
+    off(event: string, handler: (params: unknown) => void): void;
+}
+export declare class InterceptionUnavailableError extends Error {
+    readonly code = "navigation_redirect_requires_interception";
+    constructor(detail: string);
+}
+export declare class NavigationBlockedError extends Error {
+    readonly url: string;
+    readonly reason: UrlPolicyReason;
+    readonly code = "navigation_blocked_by_policy";
+    constructor(url: string, reason: UrlPolicyReason, detail: string);
+}
+export interface BlockedRecord {
+    url: string;
+    reason: UrlPolicyReason;
+}
+export interface NavigationGuard {
+    /** URLs that were failRequest'd by policy (initial + redirects). */
+    readonly blocked: ReadonlyArray<BlockedRecord>;
+    /** remoteIPAddress values observed post-connect (logged, not a boundary). */
+    readonly observedIps: ReadonlyArray<string>;
+    /** Tear down interception + listeners. Idempotent. */
+    dispose(): Promise<void>;
+}
+/**
+ * Arm Fetch interception and policy re-check, fail-closed. Must be called and
+ * resolved BEFORE the caller issues Page.navigate. Throws
+ * InterceptionUnavailableError if Fetch cannot be enabled.
+ */
+export declare function armNavigationGuard(bridge: InterceptBridge, resolver: DnsResolver, opts?: {
+    allowLiteralIp?: boolean;
+    observeIp?: boolean;
+}): Promise<NavigationGuard>;
+/**
+ * Full guarded navigation for the direct-CDP path. Pre-checks the URL, arms the
+ * guard, runs the caller-supplied navigate thunk (which issues Page.navigate), and
+ * keeps the guard live for redirects until the caller disposes it.
+ *
+ * Returns the live guard so the caller can inspect blocked/observedIps and dispose
+ * after the page settles. Throws NavigationBlockedError if the initial target fails
+ * policy (we never arm/navigate to a known-bad target), or
+ * InterceptionUnavailableError if interception cannot be armed.
+ */
+export declare function guardedNavigate(bridge: InterceptBridge, url: string, resolver: DnsResolver, navigate: () => Promise<void>, opts?: {
+    allowLiteralIp?: boolean;
+    observeIp?: boolean;
+}): Promise<NavigationGuard>;
+/** Convenience: synchronous pre-screen without DNS, for callers that only have the
+ *  syntax layer available (e.g. the extension service worker, which cannot resolve). */
+export declare function screenSyntaxOnly(url: string, opts?: {
+    allowLiteralIp?: boolean;
+}): import("./url-policy.js").UrlPolicyResult;