@sovovs/bycli 1.8.0 → 2.0.0

package/dist/src/browser/navigation-guard.js

@@ -0,0 +1,142 @@
+/**
+ * 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 { checkUrlPolicy, checkUrlSyntax } from './url-policy.js';
+export class InterceptionUnavailableError extends Error {
+    code = 'navigation_redirect_requires_interception';
+    constructor(detail) {
+        super(`navigation request interception unavailable: ${detail}`);
+        this.name = 'InterceptionUnavailableError';
+    }
+}
+export class NavigationBlockedError extends Error {
+    url;
+    reason;
+    code = 'navigation_blocked_by_policy';
+    constructor(url, reason, detail) {
+        super(`navigation blocked: ${detail}`);
+        this.url = url;
+        this.reason = reason;
+        this.name = 'NavigationBlockedError';
+    }
+}
+/**
+ * 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 async function armNavigationGuard(bridge, resolver, opts = {}) {
+    const blocked = [];
+    const observedIps = [];
+    // Fetch.enable scoped to top-level documents at the Request stage so we block
+    // before the request is sent. resourceType uses Network.ResourceType values;
+    // 'Document' is the main frame (P1-1).
+    try {
+        await bridge.send('Fetch.enable', {
+            patterns: [{ urlPattern: '*', resourceType: 'Document', requestStage: 'Request' }],
+        });
+    }
+    catch (err) {
+        throw new InterceptionUnavailableError(err instanceof Error ? err.message : String(err));
+    }
+    const onPaused = (raw) => {
+        const p = raw;
+        // Only enforce policy on main-frame Document requests; let sub-resources through
+        // unmodified (page sub-resource SSRF is out of scope for the navigation spike).
+        if (p.resourceType !== 'Document') {
+            void bridge.send('Fetch.continueRequest', { requestId: p.requestId }).catch(() => { });
+            return;
+        }
+        void (async () => {
+            const verdict = await checkUrlPolicy(p.request.url, resolver, opts).catch(() => null);
+            if (verdict && verdict.ok) {
+                await bridge.send('Fetch.continueRequest', { requestId: p.requestId }).catch(() => { });
+            }
+            else {
+                if (verdict && !verdict.ok)
+                    blocked.push({ url: p.request.url, reason: verdict.reason });
+                // BlockedByClient → the request is never sent to the target.
+                await bridge
+                    .send('Fetch.failRequest', { requestId: p.requestId, errorReason: 'BlockedByClient' })
+                    .catch(() => { });
+            }
+        })();
+    };
+    const onResponse = (raw) => {
+        const p = raw;
+        const ip = p.response?.remoteIPAddress;
+        if (ip)
+            observedIps.push(ip);
+    };
+    bridge.on('Fetch.requestPaused', onPaused);
+    if (opts.observeIp) {
+        // Network domain must be enabled elsewhere for this to fire; we only attach the
+        // observer. Missing IP (cache/SW/failed request) is tolerated — never a boundary.
+        bridge.on('Network.responseReceived', onResponse);
+    }
+    let disposed = false;
+    return {
+        blocked,
+        observedIps,
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            bridge.off('Fetch.requestPaused', onPaused);
+            if (opts.observeIp)
+                bridge.off('Network.responseReceived', onResponse);
+            await bridge.send('Fetch.disable').catch(() => { });
+        },
+    };
+}
+/**
+ * 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 async function guardedNavigate(bridge, url, resolver, navigate, opts = {}) {
+    // 1. Pre-check the initial target before doing anything else.
+    const pre = await checkUrlPolicy(url, resolver, opts);
+    if (!pre.ok) {
+        throw new NavigationBlockedError(url, pre.reason, pre.detail);
+    }
+    // 2. Arm interception (fail-closed) and confirm before navigating.
+    const guard = await armNavigationGuard(bridge, resolver, opts);
+    // 3. Navigate exactly once, now that the guard is live.
+    try {
+        await navigate();
+    }
+    catch (err) {
+        await guard.dispose();
+        throw err;
+    }
+    return guard;
+}
+/** 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 function screenSyntaxOnly(url, opts = {}) {
+    return checkUrlSyntax(url, opts);
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/url-policy.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Navigation URL policy (M1 spike).
+ *
+ * Pure, runtime-free validation of a navigation target against the security
+ * model in dashboard-docs/system/adapter-recorder-system/04-security-model.md and
+ * adr/0006-dns-rebinding-ip-enforcement.md.
+ *
+ * Two layers, deliberately separated:
+ *   1. checkUrlSyntax(url)        — synchronous: protocol / userinfo / literal-IP /
+ *                                    forbidden-host checks. No I/O.
+ *   2. resolveAndCheckHost(...)   — asynchronous: resolves every A/AAAA record for a
+ *                                    *domain* host and rejects if any resolved IP is
+ *                                    forbidden. DNS resolver is injected for testing.
+ *
+ * SECURITY BOUNDARY NOTE (ADR-0006): the DNS precheck in layer 2 filters only the
+ * records visible *at check time*. It does NOT prove the IP the browser actually
+ * connects to (separate resolver, DNS cache, proxy, Happy Eyeballs, TTL-window
+ * rebind). This TOCTOU window is not removable here. Passing this policy is
+ * `ip-observed-only`, never `strict-ip-enforced`. Callers must still arm
+ * before-send request interception and re-run this policy on every redirected /
+ * secondary main-frame request.
+ */
+/** Why a URL was rejected. Stable codes — used by tests and error mapping. */
+export type UrlPolicyReason = 'forbidden_protocol' | 'userinfo_present' | 'empty_host' | 'literal_ip_host' | 'forbidden_ip' | 'unresolvable_host' | 'no_dns_records';
+export interface UrlPolicyOk {
+    ok: true;
+    /** Canonicalized URL string after normalization. */
+    url: string;
+    /** Normalized hostname (lowercased, trailing dot stripped, IDN punycode, IPv6 canonical). */
+    hostname: string;
+    /** True when the host was an IP literal — only reachable when allowLiteralIp is set. */
+    isIpLiteral: boolean;
+}
+export interface UrlPolicyReject {
+    ok: false;
+    reason: UrlPolicyReason;
+    /** Human detail for logs/errors (never includes secrets). */
+    detail: string;
+    /** The raw authority (host[:port]) exactly as supplied, for input-form assertions. */
+    rawAuthority?: string;
+}
+export type UrlPolicyResult = UrlPolicyOk | UrlPolicyReject;
+/** Injected DNS resolver — node:dns/promises in production, a stub in tests. */
+export interface DnsResolver {
+    resolve4(hostname: string): Promise<string[]>;
+    resolve6(hostname: string): Promise<string[]>;
+}
+/**
+ * Extract the raw authority (everything between `://` and the first `/?#`) from the
+ * input string, before any URL-parser canonicalization. Used to assert on the
+ * *input form* — e.g. that `http://0177.0.0.1/` was supplied as an octal literal —
+ * since WHATWG URL silently rewrites those into `127.0.0.1` (P1-4).
+ */
+export declare function rawAuthorityOf(input: string): string | undefined;
+/**
+ * Decide whether a hostname (already lowercased, trailing-dot stripped) is an IP
+ * literal in ANY encoding the browser would accept: dotted-decimal, IPv6 in
+ * brackets, decimal/octal/hex/shorthand IPv4. Returns the canonical IP string when
+ * it is a literal, or null when it is a real domain name.
+ */
+export declare function asIpLiteral(host: string): string | null;
+/**
+ * Parse the loose IPv4 forms browsers accept (decimal, octal, hex, 1-4 dotted
+ * parts with mixed radices). Returns canonical dotted-decimal, or null if not a
+ * valid IPv4 literal. Mirrors the "parts" algorithm in the WHATWG URL spec.
+ */
+export declare function parseIpv4Loose(host: string): string | null;
+/** True when an IP literal (v4 or v6, any normalized form) is in a forbidden range. */
+export declare function isForbiddenIp(ip: string): boolean;
+/**
+ * Synchronous URL syntax + literal-host policy. No DNS, no I/O.
+ *
+ * @param input         raw navigation URL
+ * @param opts.allowLiteralIp  when true, an IP-literal host is allowed *if* it is
+ *                             not in a forbidden range (used by tooling that
+ *                             targets explicit IPs); default false — navigation
+ *                             targets must be domain names.
+ */
+export declare function checkUrlSyntax(input: string, opts?: {
+    allowLiteralIp?: boolean;
+}): UrlPolicyResult;
+/**
+ * Full policy: syntax check, then resolve every A/AAAA record for a domain host and
+ * reject if any resolved IP is forbidden (DNS precheck — see SECURITY BOUNDARY NOTE).
+ * IP-literal hosts skip DNS (already vetted by checkUrlSyntax).
+ */
+export declare function checkUrlPolicy(input: string, resolver: DnsResolver, opts?: {
+    allowLiteralIp?: boolean;
+}): Promise<UrlPolicyResult>;

package/dist/src/browser/url-policy.js

@@ -0,0 +1,311 @@
+/**
+ * Navigation URL policy (M1 spike).
+ *
+ * Pure, runtime-free validation of a navigation target against the security
+ * model in dashboard-docs/system/adapter-recorder-system/04-security-model.md and
+ * adr/0006-dns-rebinding-ip-enforcement.md.
+ *
+ * Two layers, deliberately separated:
+ *   1. checkUrlSyntax(url)        — synchronous: protocol / userinfo / literal-IP /
+ *                                    forbidden-host checks. No I/O.
+ *   2. resolveAndCheckHost(...)   — asynchronous: resolves every A/AAAA record for a
+ *                                    *domain* host and rejects if any resolved IP is
+ *                                    forbidden. DNS resolver is injected for testing.
+ *
+ * SECURITY BOUNDARY NOTE (ADR-0006): the DNS precheck in layer 2 filters only the
+ * records visible *at check time*. It does NOT prove the IP the browser actually
+ * connects to (separate resolver, DNS cache, proxy, Happy Eyeballs, TTL-window
+ * rebind). This TOCTOU window is not removable here. Passing this policy is
+ * `ip-observed-only`, never `strict-ip-enforced`. Callers must still arm
+ * before-send request interception and re-run this policy on every redirected /
+ * secondary main-frame request.
+ */
+import { isIP } from 'node:net';
+const ALLOWED_PROTOCOLS = new Set(['http:', 'https:']);
+/**
+ * Extract the raw authority (everything between `://` and the first `/?#`) from the
+ * input string, before any URL-parser canonicalization. Used to assert on the
+ * *input form* — e.g. that `http://0177.0.0.1/` was supplied as an octal literal —
+ * since WHATWG URL silently rewrites those into `127.0.0.1` (P1-4).
+ */
+export function rawAuthorityOf(input) {
+    const m = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/([^/?#]*)/.exec(input.trim());
+    if (!m)
+        return undefined;
+    // Strip userinfo for the authority-host portion but keep the host[:port].
+    const authority = m[1];
+    const at = authority.lastIndexOf('@');
+    return at >= 0 ? authority.slice(at + 1) : authority;
+}
+/**
+ * Decide whether a hostname (already lowercased, trailing-dot stripped) is an IP
+ * literal in ANY encoding the browser would accept: dotted-decimal, IPv6 in
+ * brackets, decimal/octal/hex/shorthand IPv4. Returns the canonical IP string when
+ * it is a literal, or null when it is a real domain name.
+ */
+export function asIpLiteral(host) {
+    // IPv6 literal arrives bracketed from URL.hostname only when constructed from a
+    // bracketed form; URL strips the brackets, so test the bare form too.
+    const unbracketed = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+    const v = isIP(unbracketed);
+    if (v === 4 || v === 6)
+        return unbracketed;
+    // IPv4 alternative encodings: decimal (2130706433), octal (0177.0.0.1),
+    // hex (0x7f.0.0.1), and shorthand (127.1). WHATWG URL already canonicalizes
+    // most of these, but we re-derive defensively in case a caller bypasses it.
+    const parsed = parseIpv4Loose(host);
+    return parsed;
+}
+/**
+ * Parse the loose IPv4 forms browsers accept (decimal, octal, hex, 1-4 dotted
+ * parts with mixed radices). Returns canonical dotted-decimal, or null if not a
+ * valid IPv4 literal. Mirrors the "parts" algorithm in the WHATWG URL spec.
+ */
+export function parseIpv4Loose(host) {
+    if (host.length === 0)
+        return null;
+    const parts = host.split('.');
+    // A trailing empty part (from a trailing dot) is tolerated by the spec; reject
+    // here since trailing dots are stripped before this is called.
+    if (parts.length > 4)
+        return null;
+    if (parts.some((p) => p.length === 0))
+        return null;
+    const numbers = [];
+    for (const part of parts) {
+        const n = parseRadixPart(part);
+        if (n === null)
+            return null;
+        numbers.push(n);
+    }
+    // Each non-final part must fit in a byte; the final part absorbs the remaining bytes.
+    for (let i = 0; i < numbers.length - 1; i++) {
+        if (numbers[i] > 255)
+            return null;
+    }
+    const last = numbers[numbers.length - 1];
+    const maxLast = 256 ** (5 - numbers.length);
+    if (last >= maxLast)
+        return null;
+    let ipv4 = last;
+    for (let i = 0; i < numbers.length - 1; i++) {
+        ipv4 += numbers[i] * 256 ** (3 - i);
+    }
+    if (ipv4 > 0xffffffff)
+        return null;
+    return [
+        (ipv4 >>> 24) & 0xff,
+        (ipv4 >>> 16) & 0xff,
+        (ipv4 >>> 8) & 0xff,
+        ipv4 & 0xff,
+    ].join('.');
+}
+function parseRadixPart(part) {
+    let radix = 10;
+    let digits = part;
+    if (/^0[xX]/.test(part)) {
+        radix = 16;
+        digits = part.slice(2);
+        if (digits.length === 0)
+            return null;
+        if (!/^[0-9a-fA-F]+$/.test(digits))
+            return null;
+    }
+    else if (part.length > 1 && part[0] === '0') {
+        radix = 8;
+        digits = part.slice(1);
+        if (!/^[0-7]+$/.test(digits))
+            return null;
+    }
+    else {
+        if (!/^[0-9]+$/.test(part))
+            return null;
+    }
+    const n = parseInt(digits, radix);
+    return Number.isNaN(n) ? null : n;
+}
+/** IPv4 forbidden ranges as [network, prefixBits] CIDR pairs. */
+const FORBIDDEN_IPV4 = [
+    ['0.0.0.0', 8], // "this" network / unspecified
+    ['10.0.0.0', 8], // RFC1918 private
+    ['100.64.0.0', 10], // RFC6598 CGNAT
+    ['127.0.0.0', 8], // loopback
+    ['169.254.0.0', 16], // link-local (incl. 169.254.169.254 cloud metadata)
+    ['172.16.0.0', 12], // RFC1918 private
+    ['192.0.0.0', 24], // IETF protocol assignments
+    ['192.0.2.0', 24], // TEST-NET-1 documentation
+    ['192.168.0.0', 16], // RFC1918 private
+    ['198.18.0.0', 15], // RFC2544 benchmarking
+    ['198.51.100.0', 24], // TEST-NET-2 documentation
+    ['203.0.113.0', 24], // TEST-NET-3 documentation
+    ['224.0.0.0', 4], // multicast
+    ['240.0.0.0', 4], // reserved (incl. 255.255.255.255 broadcast)
+];
+function ipv4ToInt(ip) {
+    const parts = ip.split('.').map((p) => parseInt(p, 10));
+    return ((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>> 0;
+}
+function ipv4InForbiddenRange(ip) {
+    const addr = ipv4ToInt(ip);
+    for (const [net, bits] of FORBIDDEN_IPV4) {
+        const mask = bits === 0 ? 0 : (0xffffffff << (32 - bits)) >>> 0;
+        if ((addr & mask) === (ipv4ToInt(net) & mask))
+            return true;
+    }
+    return false;
+}
+/** Expand an IPv6 address to its 8 16-bit groups (numbers), handling `::` and
+ *  embedded IPv4 tails. Returns null when not a valid IPv6 literal. */
+function ipv6Groups(ip) {
+    let addr = ip;
+    // Embedded IPv4 tail (e.g. ::ffff:127.0.0.1 or 64:ff9b::192.0.2.1).
+    const lastColon = addr.lastIndexOf(':');
+    const tail = addr.slice(lastColon + 1);
+    if (tail.includes('.')) {
+        if (isIP(tail) !== 4)
+            return null;
+        const v4 = ipv4ToInt(tail);
+        addr = addr.slice(0, lastColon + 1) + ((v4 >>> 16) & 0xffff).toString(16) + ':' + (v4 & 0xffff).toString(16);
+    }
+    const halves = addr.split('::');
+    if (halves.length > 2)
+        return null;
+    const head = halves[0].length ? halves[0].split(':') : [];
+    const back = halves.length === 2 ? (halves[1].length ? halves[1].split(':') : []) : null;
+    const parse = (groups) => {
+        const out = [];
+        for (const g of groups) {
+            if (!/^[0-9a-fA-F]{1,4}$/.test(g))
+                return null;
+            out.push(parseInt(g, 16));
+        }
+        return out;
+    };
+    const headNums = parse(head);
+    if (headNums === null)
+        return null;
+    if (back === null) {
+        return headNums.length === 8 ? headNums : null;
+    }
+    const backNums = parse(back);
+    if (backNums === null)
+        return null;
+    const fill = 8 - headNums.length - backNums.length;
+    if (fill < 0)
+        return null;
+    return [...headNums, ...new Array(fill).fill(0), ...backNums];
+}
+function ipv6InForbiddenRange(ip) {
+    const groups = ipv6Groups(ip);
+    if (!groups)
+        return false;
+    // Unspecified ::  and loopback ::1
+    if (groups.every((g) => g === 0))
+        return true; // ::
+    if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1)
+        return true; // ::1
+    // IPv4-mapped ::ffff:0:0/96 and IPv4-compatible — defer to the embedded v4 range check.
+    if (groups.slice(0, 5).every((g) => g === 0) && groups[5] === 0xffff) {
+        const v4 = `${(groups[6] >> 8) & 0xff}.${groups[6] & 0xff}.${(groups[7] >> 8) & 0xff}.${groups[7] & 0xff}`;
+        return ipv4InForbiddenRange(v4);
+    }
+    const first = groups[0];
+    // fc00::/7 unique-local
+    if ((first & 0xfe00) === 0xfc00)
+        return true;
+    // fe80::/10 link-local
+    if ((first & 0xffc0) === 0xfe80)
+        return true;
+    // ff00::/8 multicast
+    if ((first & 0xff00) === 0xff00)
+        return true;
+    // fd00:ec2::254 cloud metadata is inside fc00::/7, already covered.
+    return false;
+}
+/** True when an IP literal (v4 or v6, any normalized form) is in a forbidden range. */
+export function isForbiddenIp(ip) {
+    const v = isIP(ip);
+    if (v === 4)
+        return ipv4InForbiddenRange(ip);
+    if (v === 6)
+        return ipv6InForbiddenRange(ip);
+    // Loose IPv4 encodings normalize first.
+    const canon = parseIpv4Loose(ip);
+    return canon ? ipv4InForbiddenRange(canon) : false;
+}
+/**
+ * Synchronous URL syntax + literal-host policy. No DNS, no I/O.
+ *
+ * @param input         raw navigation URL
+ * @param opts.allowLiteralIp  when true, an IP-literal host is allowed *if* it is
+ *                             not in a forbidden range (used by tooling that
+ *                             targets explicit IPs); default false — navigation
+ *                             targets must be domain names.
+ */
+export function checkUrlSyntax(input, opts = {}) {
+    const rawAuthority = rawAuthorityOf(input);
+    let parsed;
+    try {
+        parsed = new URL(input);
+    }
+    catch {
+        return { ok: false, reason: 'empty_host', detail: 'unparseable URL', rawAuthority };
+    }
+    if (!ALLOWED_PROTOCOLS.has(parsed.protocol)) {
+        return { ok: false, reason: 'forbidden_protocol', detail: `protocol ${parsed.protocol} not allowed`, rawAuthority };
+    }
+    if (parsed.username !== '' || parsed.password !== '') {
+        return { ok: false, reason: 'userinfo_present', detail: 'userinfo (user:pass@) not allowed', rawAuthority };
+    }
+    // Normalize hostname: URL already lowercases, IDN-punycodes, and canonicalizes
+    // IPv6; strip a trailing dot ourselves.
+    let hostname = parsed.hostname;
+    if (hostname.endsWith('.'))
+        hostname = hostname.slice(0, -1);
+    if (hostname === '') {
+        return { ok: false, reason: 'empty_host', detail: 'empty host', rawAuthority };
+    }
+    const ipLiteral = asIpLiteral(hostname);
+    if (ipLiteral !== null) {
+        if (isForbiddenIp(ipLiteral)) {
+            return { ok: false, reason: 'forbidden_ip', detail: `literal IP ${ipLiteral} is forbidden`, rawAuthority };
+        }
+        if (!opts.allowLiteralIp) {
+            return { ok: false, reason: 'literal_ip_host', detail: `literal IP host ${ipLiteral} not allowed for navigation`, rawAuthority };
+        }
+        return { ok: true, url: parsed.toString(), hostname: ipLiteral, isIpLiteral: true };
+    }
+    return { ok: true, url: parsed.toString(), hostname, isIpLiteral: false };
+}
+/**
+ * Full policy: syntax check, then resolve every A/AAAA record for a domain host and
+ * reject if any resolved IP is forbidden (DNS precheck — see SECURITY BOUNDARY NOTE).
+ * IP-literal hosts skip DNS (already vetted by checkUrlSyntax).
+ */
+export async function checkUrlPolicy(input, resolver, opts = {}) {
+    const syntax = checkUrlSyntax(input, opts);
+    if (!syntax.ok)
+        return syntax;
+    if (syntax.isIpLiteral)
+        return syntax;
+    let records;
+    try {
+        const [v4, v6] = await Promise.all([
+            resolver.resolve4(syntax.hostname).catch(() => []),
+            resolver.resolve6(syntax.hostname).catch(() => []),
+        ]);
+        records = [...v4, ...v6];
+    }
+    catch {
+        return { ok: false, reason: 'unresolvable_host', detail: `DNS resolution failed for ${syntax.hostname}` };
+    }
+    if (records.length === 0) {
+        return { ok: false, reason: 'no_dns_records', detail: `no A/AAAA records for ${syntax.hostname}` };
+    }
+    for (const ip of records) {
+        if (isForbiddenIp(ip)) {
+            return { ok: false, reason: 'forbidden_ip', detail: `${syntax.hostname} resolves to forbidden IP ${ip}` };
+        }
+    }
+    return syntax;
+}

package/dist/src/browser/url-policy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/verify-fixture.js

@@ -28,8 +28,8 @@
  *   }
  */
 import * as fs from 'node:fs';
-import * as os from 'node:os';
 import * as path from 'node:path';
+import { getSitesDir } from '../config-paths.js';
 const DEFAULT_MAX_TOP_LEVEL_KEYS = 12;
 const DEFAULT_MAX_NESTED_DEPTH = 1;
 const ID_SHAPED_KEY_PATTERNS = [
@@ -51,7 +51,7 @@ const ID_SHAPED_KEY_PATTERNS = [
     /^uri$/i,
 ];
 export function fixturePath(site, command) {
-    return path.join(os.homedir(), '.bycli', 'sites', site, 'verify', `${command}.json`);
+    return path.join(getSitesDir(), site, 'verify', `${command}.json`);
 }
 export function loadFixture(site, command) {
     const p = fixturePath(site, command);

package/dist/src/cli.js

@@ -8,6 +8,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { getUserClisDir, getSitesDir } from './config-paths.js';
 import { Command, InvalidArgumentError, Option } from 'commander';
 import { findPackageRoot, getBuiltEntryCandidates } from './package-paths.js';
 import { fullName, getRegistry, strategyLabel } from './registry.js';
@@ -148,7 +149,7 @@ function emitNetworkError(code, message, extra = {}) {
     process.exitCode = NETWORK_ERROR_EXIT[code] ?? EXIT_CODES.GENERIC_ERROR;
 }
 export function checkSiteMemory(site) {
-    const siteDir = path.join(os.homedir(), '.bycli', 'sites', site);
+    const siteDir = path.join(getSitesDir(), site);
     const endpointsPath = path.join(siteDir, 'endpoints.json');
     const notesPath = path.join(siteDir, 'notes.md');
     let endpointsCount = 0;
@@ -2357,10 +2358,9 @@ Examples:
                 process.exitCode = EXIT_CODES.USAGE_ERROR;
                 return;
             }
-            const os = await import('node:os');
             const fs = await import('node:fs');
             const path = await import('node:path');
-            const dir = path.join(os.homedir(), '.bycli', 'clis', site);
+            const dir = path.join(getUserClisDir(), site);
             const filePath = path.join(dir, `${command}.js`);
             if (fs.existsSync(filePath)) {
                 console.log(`Adapter already exists: ${filePath}`);
@@ -2427,7 +2427,7 @@ cli({
             }
             const { execFileSync } = await import('node:child_process');
             const { loadFixture, writeFixture, deriveFixture, validateRows, validateRowShape, fixturePath, expandFixtureArgs, parseSeedArgs } = await import('./browser/verify-fixture.js');
-            const filePath = path.join(os.homedir(), '.bycli', 'clis', site, `${command}.js`);
+            const filePath = path.join(getUserClisDir(), site, `${command}.js`);
             if (!fs.existsSync(filePath)) {
                 console.error(`Adapter not found: ${filePath}`);
                 console.error(`Run "bycli browser init ${name}" to create it.`);
@@ -2773,8 +2773,7 @@ cli({
         .command('status')
         .description('Show which sites have local overrides vs using official baseline')
         .action(async () => {
-        const os = await import('node:os');
-        const userClisDir = path.join(os.homedir(), '.bycli', 'clis');
+        const userClisDir = getUserClisDir();
         const builtinClisDir = BUILTIN_CLIS;
         try {
             const userEntries = await fs.promises.readdir(userClisDir, { withFileTypes: true });
@@ -2789,7 +2788,7 @@ cli({
                 console.log('No local adapter overrides. All sites use the official baseline.');
                 return;
             }
-            console.log(`Local overrides in ~/.bycli/clis/ (${userSites.length} sites):\n`);
+            console.log(`Local overrides in ${userClisDir} (${userSites.length} sites):\n`);
             for (const site of userSites) {
                 const isOfficial = builtinSites.includes(site);
                 const label = isOfficial ? 'override' : 'custom';
@@ -2806,8 +2805,7 @@ cli({
         .description('Copy an official adapter to ~/.bycli/clis/ for local editing')
         .argument('<site>', 'Site name (e.g. twitter, bilibili)')
         .action(async (site) => {
-        const os = await import('node:os');
-        const userClisDir = path.join(os.homedir(), '.bycli', 'clis');
+        const userClisDir = getUserClisDir();
         const builtinSiteDir = path.join(BUILTIN_CLIS, site);
         const userSiteDir = path.join(userClisDir, site);
         try {
@@ -2820,13 +2818,13 @@ cli({
         }
         try {
             await fs.promises.access(userSiteDir);
-            console.error(`Site "${site}" already exists in ~/.bycli/clis/. Use "bycli adapter reset ${site}" first to restore official version.`);
+            console.error(`Site "${site}" already exists in ${userClisDir}. Use "bycli adapter reset ${site}" first to restore official version.`);
             process.exitCode = EXIT_CODES.USAGE_ERROR;
             return;
         }
         catch { /* good, doesn't exist yet */ }
         fs.cpSync(builtinSiteDir, userSiteDir, { recursive: true });
-        console.log(`✅ Ejected "${site}" to ~/.bycli/clis/${site}/`);
+        console.log(`✅ Ejected "${site}" to ${userSiteDir}/`);
         console.log('You can now edit the adapter files. Changes take effect immediately.');
         console.log('Note: Official updates to this adapter will overwrite your changes.');
     });
@@ -2836,8 +2834,7 @@ cli({
         .argument('[site]', 'Site name (e.g. twitter, bilibili)')
         .option('--all', 'Reset all local overrides')
         .action(async (site, opts) => {
-        const os = await import('node:os');
-        const userClisDir = path.join(os.homedir(), '.bycli', 'clis');
+        const userClisDir = getUserClisDir();
         if (opts.all) {
             try {
                 const userEntries = await fs.promises.readdir(userClisDir, { withFileTypes: true });

package/dist/src/config-paths.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolvers for the byCLI user-data root and its well-known subdirectories.
+ *
+ * The root is `BYCLI_CONFIG_DIR` when set, else `~/.bycli`. These are FUNCTIONS,
+ * not module-level constants, on purpose: `BYCLI_CONFIG_DIR` is set dynamically
+ * (tests, the verify child sandbox in runner-port.ts) — a const captured at import
+ * time would freeze the wrong root and leak across tests. Always resolve on call.
+ *
+ * Existing duplicate idioms this consolidates: observation/artifact.ts, browser/profile.ts.
+ */
+export declare function getConfigDir(): string;
+/** User adapter root: `$CONFIG_DIR/clis`. Adapters live at `<clis>/<site>/<command>.js`. */
+export declare function getUserClisDir(): string;
+/** Per-site memory/recorder root: `$CONFIG_DIR/sites`. */
+export declare function getSitesDir(): string;
+/** A single site's directory: `$CONFIG_DIR/sites/<site>`. */
+export declare function getSiteDir(site: string): string;
+/** A site's recorder artifact dir: `$CONFIG_DIR/sites/<site>/recorder`. */
+export declare function getSiteRecorderDir(site: string): string;