barebrowse 0.25.0 → 0.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,184 @@
1
+ /**
2
+ * site-lock.js — Optional top-frame site lock (`allowHosts`).
3
+ *
4
+ * Top-level navigations (goto, redirect hops, clicked links, JS jumps, popups)
5
+ * to a host outside the allow list are failed in the browser before any request
6
+ * leaves, so the page stays put. Deliberately NOT locked: subresources
7
+ * (img/script/css/XHR/fetch), iframes, WebSocket — the lock stops an agent
8
+ * being steered to another site, not the page from loading its own assets.
9
+ * The engine wiring lives next to each transport (applySiteLockCDP here,
10
+ * blocklist-firefox.js for BiDi); this file is the shared policy + state.
11
+ */
12
+
13
+ import { navBlocked } from './navigation.js';
14
+
15
+ const HOST_RE = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/;
16
+
17
+ /**
18
+ * Validate and normalize an allow list. Entry = `host` or `*.host`; anything
19
+ * else (scheme, port, path, spaces, empty, bare `*`) throws — a typo must never
20
+ * silently widen or drop the lock.
21
+ * @param {string[]} list
22
+ * @returns {string[]} lowercase entries
23
+ */
24
+ export function parseAllowHosts(list) {
25
+ if (!Array.isArray(list) || !list.length) throw new Error('allowHosts must be a non-empty array of hostnames');
26
+ return list.map((raw) => {
27
+ const e = typeof raw === 'string' ? raw.trim().toLowerCase() : raw;
28
+ const host = typeof e === 'string' && e.startsWith('*.') ? e.slice(2) : e;
29
+ if (typeof host !== 'string' || !HOST_RE.test(host) || host.includes('..')) {
30
+ throw new Error(`allowHosts: invalid entry ${JSON.stringify(raw)} (expected "host" or "*.host", no scheme/port/path)`);
31
+ }
32
+ return e;
33
+ });
34
+ }
35
+
36
+ /**
37
+ * Build a URL matcher from an allow list. Non-http(s) URLs (about:, data:,
38
+ * blob:) are allowed; `host` matches that host exactly, `*.host` matches its
39
+ * strict subdomains only (not `host` itself). An unparseable URL is refused.
40
+ * @param {string[]} list
41
+ * @returns {(url: string) => boolean}
42
+ */
43
+ export function makeHostMatcher(list) {
44
+ const entries = parseAllowHosts(list);
45
+ const exact = new Set(entries.filter((e) => !e.startsWith('*.')));
46
+ const suffixes = entries.filter((e) => e.startsWith('*.')).map((e) => e.slice(1)); // ".host"
47
+ return (url) => {
48
+ let u;
49
+ try { u = new URL(url); } catch { return false; }
50
+ if (u.protocol !== 'http:' && u.protocol !== 'https:') return true;
51
+ const host = u.hostname.replace(/\.$/, '');
52
+ return exact.has(host) || suffixes.some((s) => host.endsWith(s));
53
+ };
54
+ }
55
+
56
+ /**
57
+ * The lock's shared state, one per connect()/browse() call, surviving
58
+ * relaunches and new tabs (each transport just keeps calling record()).
59
+ * @param {string[]} list
60
+ */
61
+ export function createSiteLock(list) {
62
+ const allowed = makeHostMatcher(list);
63
+ const hostOf = (url) => { try { return new URL(url).hostname; } catch { return url; } };
64
+ /** @type {{url: string, host: string, ctx: string}[]} */
65
+ let gotoBlocks = [];
66
+ // Snapshot notes belong to the tab/context where the block happened, so one
67
+ // tab's (or a popup's, shown if the agent switches to it) never leak into another's.
68
+ /** @type {Map<string, Set<string>>} */
69
+ const noted = new Map();
70
+ return {
71
+ allowed,
72
+ /** @param {string} url @throws NAV_BLOCKED when url is off the list */
73
+ assertAllowed(url) {
74
+ if (!allowed(url)) throw navBlocked(url, hostOf(url));
75
+ },
76
+ /** A top-level document request was refused. ctx = tab/context it belongs to. */
77
+ record(url, ctx) {
78
+ const host = hostOf(url);
79
+ gotoBlocks.push({ url, host, ctx });
80
+ const hosts = noted.get(ctx) ?? new Set();
81
+ noted.set(ctx, hosts.add(host));
82
+ },
83
+ /** Call right before a goto navigates; drops that tab's pending notes too. */
84
+ startGoto(ctx) { gotoBlocks = []; noted.delete(ctx); },
85
+ /**
86
+ * The block that hit this goto's own tab (a popup's block is not the
87
+ * goto's), consumed; it is reported as NAV_BLOCKED, so no snapshot note.
88
+ */
89
+ takeGotoBlock(ctx) {
90
+ const b = gotoBlocks.find((x) => x.ctx === ctx);
91
+ if (!b) return null;
92
+ gotoBlocks = gotoBlocks.filter((x) => x !== b);
93
+ noted.get(ctx)?.delete(b.host);
94
+ return { url: b.url, host: b.host };
95
+ },
96
+ /** Snapshot lines for this tab's in-page blocked jumps since the last call. */
97
+ takeNotes(ctx) {
98
+ const out = [...(noted.get(ctx) ?? [])].map((h) => `[blocked navigation to ${h}]\n`).join('');
99
+ noted.delete(ctx);
100
+ return out;
101
+ },
102
+ };
103
+ }
104
+
105
+ /** @typedef {ReturnType<typeof createSiteLock>} SiteLock */
106
+
107
+ /**
108
+ * Chromium: lock every page target of this browser. A BROWSER-level
109
+ * Fetch.enable (root client, no sessionId) pauses document requests of every
110
+ * target, popups included, so one handler covers tabs we create later and
111
+ * windows the page opens itself. A request is top-level when its frameId is a
112
+ * page target id (OOPIF iframes are 'iframe' targets, subframes share their
113
+ * parent's id space). 'Aborted' (not BlockedByClient) fails the request but
114
+ * keeps the old page instead of swapping in a chrome-error:// page.
115
+ * Call once per CDP connection, before the first navigation.
116
+ * @param {object} cdp - root CDP client
117
+ * @param {SiteLock} lock
118
+ */
119
+ export async function applySiteLockCDP(cdp, lock) {
120
+ const pageTargets = new Set();
121
+ const subframes = new Set(); // ids a refresh proved are not page targets
122
+ cdp.on('Target.targetCreated', ({ targetInfo }) => {
123
+ if (targetInfo.type === 'page') pageTargets.add(targetInfo.targetId);
124
+ });
125
+ cdp.on('Target.targetDestroyed', ({ targetId }) => pageTargets.delete(targetId));
126
+ await cdp.send('Target.setDiscoverTargets', { discover: true });
127
+
128
+ cdp.on('Fetch.requestPaused', async (p, sessionId) => {
129
+ // A popup's create event can lag its first request: ask the browser
130
+ // before treating an unknown frame as a subframe (and if that fails,
131
+ // fail closed: treat it as top-level).
132
+ if (!pageTargets.has(p.frameId) && !subframes.has(p.frameId)) {
133
+ try {
134
+ const { targetInfos } = await cdp.send('Target.getTargets');
135
+ for (const t of targetInfos) if (t.type === 'page') pageTargets.add(t.targetId);
136
+ if (!pageTargets.has(p.frameId)) subframes.add(p.frameId);
137
+ } catch { pageTargets.add(p.frameId); }
138
+ }
139
+ const ok = !pageTargets.has(p.frameId) || lock.allowed(p.request.url);
140
+ if (!ok) lock.record(p.request.url, p.frameId);
141
+ try {
142
+ if (ok) await cdp.send('Fetch.continueRequest', { requestId: p.requestId }, sessionId);
143
+ else await cdp.send('Fetch.failRequest', { requestId: p.requestId, errorReason: 'Aborted' }, sessionId);
144
+ } catch { /* target closed between the pause and our reply */ }
145
+ });
146
+ await cdp.send('Fetch.enable', { patterns: [{ resourceType: 'Document', requestStage: 'Request' }] });
147
+ }
148
+
149
+ /**
150
+ * Firefox/BiDi: build the "is this paused request a locked top-level load?"
151
+ * check that blocklist-firefox.js's single intercept handler calls (two
152
+ * catch-all handlers on one paused request would race — one continues before
153
+ * the other fails). A request is a top-level document load when it carries a
154
+ * navigation id and its context has no parent. Context ids are tracked from
155
+ * contextCreated and refreshed from getTree when an unknown one shows up, so a
156
+ * popup whose create event lags its first request can't slip through; one that
157
+ * is still unknown after the refresh is treated as top-level (fail closed).
158
+ * Redirect hops arrive as their own beforeRequestSent, so each is checked.
159
+ * @param {object} bidi - BiDi client
160
+ * @param {SiteLock} lock
161
+ * @returns {Promise<(e: object) => Promise<boolean>>} true = fail this request
162
+ */
163
+ export async function createFirefoxLockCheck(bidi, lock) {
164
+ const tops = new Set();
165
+ const known = new Set();
166
+ async function refresh() {
167
+ const { contexts } = await bidi.send('browsingContext.getTree', {});
168
+ (function walk(nodes, top) {
169
+ for (const n of nodes) { known.add(n.context); if (top) tops.add(n.context); walk(n.children || [], false); }
170
+ })(contexts, true);
171
+ }
172
+ bidi.on('browsingContext.contextCreated', (c) => { known.add(c.context); if (!c.parent) tops.add(c.context); });
173
+ bidi.on('browsingContext.contextDestroyed', (c) => { known.delete(c.context); tops.delete(c.context); });
174
+ await bidi.subscribe(['browsingContext.contextCreated', 'browsingContext.contextDestroyed']);
175
+ await refresh();
176
+ return async (e) => {
177
+ if (e.navigation == null) return false; // subresource
178
+ if (!known.has(e.context)) { try { await refresh(); } catch { tops.add(e.context); } }
179
+ if (known.has(e.context) && !tops.has(e.context)) return false; // iframe
180
+ if (lock.allowed(e.request.url)) return false;
181
+ lock.record(e.request.url, e.context);
182
+ return true;
183
+ };
184
+ }
package/types/aria.d.ts CHANGED
@@ -1,9 +1,3 @@
1
- /**
2
- * aria.js — Format ARIA accessibility tree nodes for agent consumption.
3
- *
4
- * Takes a nested tree (built from CDP's Accessibility.getFullAXTree)
5
- * and formats it as readable YAML-like text, similar to Playwright's ariaSnapshot.
6
- */
7
1
  /**
8
2
  * Format a nested ARIA tree as readable text output.
9
3
  *
@@ -7,9 +7,10 @@
7
7
  * @param {boolean} [pageOpts.blockAds] - false disables the default list.
8
8
  * @param {string[]} [pageOpts.blockUrls] - extra CDP-format globs; extend the
9
9
  * default unless blockAds is false, in which case they're the whole list.
10
+ * @param {import('./site-lock.js').SiteLock|null} [lock] - Site lock to enforce in the same handler.
10
11
  * @returns {Promise<void>}
11
12
  */
12
13
  export function applyFirefoxBlocklist(bidi: object, pageOpts?: {
13
14
  blockAds?: boolean | undefined;
14
15
  blockUrls?: string[] | undefined;
15
- }): Promise<void>;
16
+ }, lock?: import("./site-lock.js").SiteLock | null): Promise<void>;
package/types/data.d.ts CHANGED
@@ -2,9 +2,14 @@
2
2
  * Render a raw ARIA tree in data mode.
3
3
  *
4
4
  * @param {object} root - Root node from buildTree() (CDP vocabulary)
5
+ * @param {{ links?: boolean }} [opts] - links: the tree's link nodes carry `urls` (annotateLinks); adds the legend note
5
6
  * @returns {string} LEGEND line, then one line per record, YAML-ish like formatTree(); '' when there are no records
6
7
  */
7
- export function dataSnapshot(root: object): string;
8
+ export function dataSnapshot(root: object, opts?: {
9
+ links?: boolean;
10
+ }): string;
8
11
  /** First line of every data-mode snapshot: tells an agent with no docs how to read it. */
9
12
  export const LEGEND: "# data mode: one line per record. Tables: row \"<label>\": <column>: <value> \u00B7 \u2026 Groups: <label>: a, b, c. A title line followed by detail lines is one block, up to the next title line. Main content only; use mode \"act\" for menus and page controls.";
13
+ /** Appended to the legend only when links are on. */
14
+ export const LINKS_NOTE: " Links: \"name\" <url>.";
10
15
  export function stripLegend(s: any): any;
@@ -3,8 +3,10 @@
3
3
  * @param {object} bidi - BiDi client from createBiDi()
4
4
  * @param {object} [opts]
5
5
  * @param {'act'|'browse'|'navigate'|'full'|'read'|'data'} [opts.pruneMode='act'] - Default prune mode.
6
+ * @param {boolean} [opts.links=false] - Default for snapshot({ links }): show link URLs.
6
7
  * @param {{allowLocalUrls?: boolean, blockPrivateNetwork?: boolean}} [opts.urlGuard] - Navigation safety policy, applied on every goto().
7
8
  * @param {string} [opts.uploadDir] - When set, upload() rejects files outside this dir.
9
+ * @param {?import('./site-lock.js').SiteLock} [opts.siteLock] - Site lock (allowHosts) state; the request-level enforcement is installed by applyFirefoxBlocklist, this side maps it to NAV_BLOCKED and snapshot notes.
8
10
  * @param {boolean} [opts.incognito=false] - Clean session: injectCookies() is a no-op.
9
11
  * @param {boolean} [opts.consent=true] - Auto-dismiss cookie consent dialogs after goto().
10
12
  * @param {boolean} [opts.hybrid=false] - Relaunch headed on a bot-challenge page and retry.
@@ -13,11 +15,23 @@
13
15
  */
14
16
  export function createFirefoxPage(bidi: object, opts?: {
15
17
  pruneMode?: "data" | "act" | "browse" | "navigate" | "full" | "read" | undefined;
18
+ links?: boolean | undefined;
16
19
  urlGuard?: {
17
20
  allowLocalUrls?: boolean;
18
21
  blockPrivateNetwork?: boolean;
19
22
  } | undefined;
20
23
  uploadDir?: string | undefined;
24
+ siteLock?: {
25
+ allowed: (url: string) => boolean;
26
+ assertAllowed(url: string): void;
27
+ record(url: any, ctx: any): void;
28
+ startGoto(ctx: any): void;
29
+ takeGotoBlock(ctx: any): {
30
+ url: string;
31
+ host: string;
32
+ } | null;
33
+ takeNotes(ctx: any): string;
34
+ } | null | undefined;
21
35
  incognito?: boolean | undefined;
22
36
  consent?: boolean | undefined;
23
37
  hybrid?: boolean | undefined;
@@ -33,6 +47,8 @@ export function createFirefoxPage(bidi: object, opts?: {
33
47
  readonly context: any;
34
48
  /** Whether the last goto() landed on a bot-challenge page (parity w/ CDP). */
35
49
  readonly botBlocked: boolean;
50
+ /** Outcome of the latest goto(): `{url, status}`, or null before any goto. */
51
+ readonly lastNavigation: import("./navigation.js").NavigationOutcome | null;
36
52
  /** @type {'firefox'} Engine driving this session (see also `capabilities`). */
37
53
  engine: "firefox";
38
54
  /**
@@ -44,7 +60,7 @@ export function createFirefoxPage(bidi: object, opts?: {
44
60
  * @type {import('./index.js').Capabilities}
45
61
  */
46
62
  capabilities: import("./index.js").Capabilities;
47
- goto(url: any, timeout?: number): Promise<void>;
63
+ goto(url: any, timeout?: number): Promise<import("./navigation.js").NavigationOutcome>;
48
64
  /** @param {import('./index.js').SnapshotOptions|false} [pruneOpts] */
49
65
  snapshot(pruneOpts?: import("./index.js").SnapshotOptions | false): Promise<string>;
50
66
  readable(): Promise<any>;
package/types/index.d.ts CHANGED
@@ -26,6 +26,10 @@
26
26
  * @param {string} [opts.browser] - Source browser for cookie extraction.
27
27
  * @param {boolean} [opts.consent=true] - Auto-dismiss cookie consent dialogs.
28
28
  * @param {'act'|'browse'|'navigate'|'full'|'read'|'data'} [opts.pruneMode='act'] - Pruning mode.
29
+ * @param {boolean} [opts.links=false] - Show link URLs: `link "name" <url> [ref=N]`.
30
+ * @param {string[]} [opts.allowHosts] - Site lock: top-level navigations (the URL, its
31
+ * redirects) to hosts outside this list reject with NAV_BLOCKED. Entries are `host`
32
+ * or `*.host` (strict subdomains). Subresources and iframes are not locked.
29
33
  * @returns {Promise<string>} ARIA snapshot text
30
34
  */
31
35
  export function browse(url: string, opts?: {
@@ -48,6 +52,8 @@ export function browse(url: string, opts?: {
48
52
  browser?: string | undefined;
49
53
  consent?: boolean | undefined;
50
54
  pruneMode?: "data" | "act" | "browse" | "navigate" | "full" | "read" | undefined;
55
+ links?: boolean | undefined;
56
+ allowHosts?: string[] | undefined;
51
57
  }): Promise<string>;
52
58
  /**
53
59
  * Decide which engine connect() should use. Pure — the caller passes lazy
@@ -74,9 +80,10 @@ export function connect(opts?: {}): Promise<{
74
80
  readonly bidi: any;
75
81
  readonly context: any;
76
82
  readonly botBlocked: boolean;
83
+ readonly lastNavigation: import("./navigation.js").NavigationOutcome | null;
77
84
  engine: "firefox";
78
85
  capabilities: import("./index.js").Capabilities;
79
- goto(url: any, timeout?: number): Promise<void>;
86
+ goto(url: any, timeout?: number): Promise<import("./navigation.js").NavigationOutcome>;
80
87
  snapshot(pruneOpts?: import("./index.js").SnapshotOptions | false): Promise<string>;
81
88
  readable(): Promise<any>;
82
89
  click(ref: any): Promise<void>;
@@ -109,7 +116,7 @@ export function connect(opts?: {}): Promise<{
109
116
  waitForNavigation(timeout?: number): Promise<void>;
110
117
  close(): Promise<void>;
111
118
  } | {
112
- goto(url: any, timeout?: number): Promise<void>;
119
+ goto(url: any, timeout?: number): Promise<import("./navigation.js").NavigationOutcome>;
113
120
  goBack(): Promise<void>;
114
121
  goForward(): Promise<void>;
115
122
  reload(reloadOpts?: {}): Promise<void>;
@@ -133,6 +140,8 @@ export function connect(opts?: {}): Promise<{
133
140
  waitFor(waitOpts?: {}): Promise<void>;
134
141
  saveState(filePath: any): Promise<void>;
135
142
  readonly botBlocked: boolean;
143
+ /** Outcome of the latest goto(): `{url, status}`, or null before any goto. */
144
+ readonly lastNavigation: import("./navigation.js").NavigationOutcome | null;
136
145
  /** @type {'chromium'} Engine driving this session (see also `capabilities`) */
137
146
  engine: "chromium";
138
147
  /**
@@ -159,7 +168,7 @@ export function connect(opts?: {}): Promise<{
159
168
  /** Raw CDP session for escape hatch — getter so it survives hybrid fallback / tab swaps */
160
169
  readonly cdp: any;
161
170
  createTab(): Promise<{
162
- goto(url: any, timeout?: number): Promise<void>;
171
+ goto(url: any, timeout?: number): Promise<import("./navigation.js").NavigationOutcome>;
163
172
  readonly botBlocked: boolean;
164
173
  /** @param {string} url @param {CookieOptions} [cookieOpts] */
165
174
  injectCookies(url: string, cookieOpts?: CookieOptions): Promise<number>;
@@ -243,12 +252,22 @@ export type Capabilities = {
243
252
  */
244
253
  cookieInjection: boolean;
245
254
  };
255
+ /**
256
+ * What `goto()` resolves to: the final URL (after redirects) and the main
257
+ * document's HTTP status (0 when no HTTP response was observed, e.g. an aborted navigation).
258
+ * Network failures reject with an Error whose `code` is 'NAV_FAILED' and
259
+ * `reason` the browser's raw error string.
260
+ */
261
+ export type NavigationOutcome = import("./navigation.js").NavigationOutcome;
246
262
  /**
247
263
  * Options for `page.snapshot()`. Pass `false` instead of an object to skip
248
264
  * pruning and return the raw ARIA tree.
265
+ * `links: true` adds each link's absolute URL after its name (default off,
266
+ * or the `connect({ links })` default).
249
267
  */
250
268
  export type SnapshotOptions = {
251
269
  mode?: "act" | "browse" | "navigate" | "full" | "read" | "data";
270
+ links?: boolean;
252
271
  };
253
272
  /**
254
273
  * Options for `page.type()`.
@@ -0,0 +1,28 @@
1
+ /**
2
+ * links.js — opt-in link URLs for snapshots (`links: true`).
3
+ *
4
+ * `annotateLinks()` stamps `urls: [url]` on every link node that has a usable
5
+ * browser-serialized absolute URL. aria.js, prune.js and data.js print/carry
6
+ * `urls` — they never see the option, so with links off nothing changes.
7
+ */
8
+ /**
9
+ * Normalise a link's URL for a snapshot line. Returns '' when it should not be
10
+ * shown: no URL, `javascript:`, or a same-document link (the page URL, only
11
+ * the #fragment differs). A raw space, `<` or `>` (browsers encode them, but
12
+ * not always in the fragment) is percent-encoded so a line splits cleanly on
13
+ * ` <` and `> `.
14
+ *
15
+ * @param {string|undefined} url - Absolute URL as serialized by the browser
16
+ * @param {string} [pageUrl] - URL of the page the link is on
17
+ * @returns {string}
18
+ */
19
+ export function linkUrl(url: string | undefined, pageUrl?: string): string;
20
+ /**
21
+ * Copy a tree with `urls` set on its link nodes (input is not mutated).
22
+ *
23
+ * @param {object|null} node - Root from buildTree()
24
+ * @param {string} pageUrl
25
+ * @returns {object|null}
26
+ */
27
+ export function annotateLinks(node: object | null, pageUrl: string): object | null;
28
+ export function urlsText(urls: any): any;
@@ -0,0 +1,56 @@
1
+ /**
2
+ * navigation.js — Shared pieces of the goto() outcome contract, so both
3
+ * engines (CDP in index.js, BiDi in firefox-page.js) report it identically.
4
+ */
5
+ /**
6
+ * What goto() resolves to: where the page ended up and how the server answered.
7
+ * `status` is 0 when no HTTP response was observed for the navigation (e.g. an
8
+ * aborted navigation that never got one).
9
+ * @typedef {{ url: string, status: number }} NavigationOutcome
10
+ */
11
+ /**
12
+ * Typed error for a navigation that never reached a document (DNS failure,
13
+ * connection refused, TLS error, ...). `code` is 'NAV_FAILED'; `reason` is the
14
+ * browser's raw error string (`net::ERR_NAME_NOT_RESOLVED`,
15
+ * `NS_ERROR_UNKNOWN_HOST`, ...).
16
+ * @param {string} url
17
+ * @param {string} reason
18
+ * @returns {Error & {code: 'NAV_FAILED', reason: string}}
19
+ */
20
+ export function navFailed(url: string, reason: string): Error & {
21
+ code: "NAV_FAILED";
22
+ reason: string;
23
+ };
24
+ /**
25
+ * Typed error for a top-level navigation the site lock (`allowHosts`) refused:
26
+ * the target, or a redirect hop of it, is off the allowed list. `code` is
27
+ * 'NAV_BLOCKED'; `host` is the refused hostname. The page stays where it was.
28
+ * @param {string} url - The refused URL (the redirect target, if it was a hop).
29
+ * @param {string} host
30
+ * @returns {Error & {code: 'NAV_BLOCKED', host: string}}
31
+ */
32
+ export function navBlocked(url: string, host: string): Error & {
33
+ code: "NAV_BLOCKED";
34
+ host: string;
35
+ };
36
+ /**
37
+ * True for a final HTTP status that is not 2xx (0 = unknown is not an error).
38
+ * @param {number|undefined} status
39
+ */
40
+ export function isHttpError(status: number | undefined): boolean;
41
+ /**
42
+ * Warning line for a non-2xx final status ('' for 2xx and for unknown 0), in
43
+ * the style of the bot-challenge line, newline-terminated for prepending.
44
+ * @param {number|undefined} status
45
+ * @returns {string}
46
+ */
47
+ export function httpWarning(status: number | undefined): string;
48
+ /**
49
+ * What goto() resolves to: where the page ended up and how the server answered.
50
+ * `status` is 0 when no HTTP response was observed for the navigation (e.g. an
51
+ * aborted navigation that never got one).
52
+ */
53
+ export type NavigationOutcome = {
54
+ url: string;
55
+ status: number;
56
+ };
package/types/prune.d.ts CHANGED
@@ -5,9 +5,11 @@
5
5
  * @param {object} [options]
6
6
  * @param {'act'|'browse'|'navigate'|'full'|'read'} [options.mode='act'] - Pruning mode ('read' is an alias for 'browse')
7
7
  * @param {string} [options.context=''] - Search context for relevance filtering
8
+ * @param {boolean} [options.links=false] - Links carry `urls` (see links.js): nodes that drop their children keep the URLs of links beneath them
8
9
  * @returns {object|null} Pruned tree
9
10
  */
10
11
  export function prune(tree: object, options?: {
11
12
  mode?: "act" | "browse" | "navigate" | "full" | "read" | undefined;
12
13
  context?: string | undefined;
14
+ links?: boolean | undefined;
13
15
  }): object | null;
@@ -0,0 +1,70 @@
1
+ /**
2
+ * Validate and normalize an allow list. Entry = `host` or `*.host`; anything
3
+ * else (scheme, port, path, spaces, empty, bare `*`) throws — a typo must never
4
+ * silently widen or drop the lock.
5
+ * @param {string[]} list
6
+ * @returns {string[]} lowercase entries
7
+ */
8
+ export function parseAllowHosts(list: string[]): string[];
9
+ /**
10
+ * Build a URL matcher from an allow list. Non-http(s) URLs (about:, data:,
11
+ * blob:) are allowed; `host` matches that host exactly, `*.host` matches its
12
+ * strict subdomains only (not `host` itself). An unparseable URL is refused.
13
+ * @param {string[]} list
14
+ * @returns {(url: string) => boolean}
15
+ */
16
+ export function makeHostMatcher(list: string[]): (url: string) => boolean;
17
+ /**
18
+ * The lock's shared state, one per connect()/browse() call, surviving
19
+ * relaunches and new tabs (each transport just keeps calling record()).
20
+ * @param {string[]} list
21
+ */
22
+ export function createSiteLock(list: string[]): {
23
+ allowed: (url: string) => boolean;
24
+ /** @param {string} url @throws NAV_BLOCKED when url is off the list */
25
+ assertAllowed(url: string): void;
26
+ /** A top-level document request was refused. ctx = tab/context it belongs to. */
27
+ record(url: any, ctx: any): void;
28
+ /** Call right before a goto navigates; drops that tab's pending notes too. */
29
+ startGoto(ctx: any): void;
30
+ /**
31
+ * The block that hit this goto's own tab (a popup's block is not the
32
+ * goto's), consumed; it is reported as NAV_BLOCKED, so no snapshot note.
33
+ */
34
+ takeGotoBlock(ctx: any): {
35
+ url: string;
36
+ host: string;
37
+ } | null;
38
+ /** Snapshot lines for this tab's in-page blocked jumps since the last call. */
39
+ takeNotes(ctx: any): string;
40
+ };
41
+ /** @typedef {ReturnType<typeof createSiteLock>} SiteLock */
42
+ /**
43
+ * Chromium: lock every page target of this browser. A BROWSER-level
44
+ * Fetch.enable (root client, no sessionId) pauses document requests of every
45
+ * target, popups included, so one handler covers tabs we create later and
46
+ * windows the page opens itself. A request is top-level when its frameId is a
47
+ * page target id (OOPIF iframes are 'iframe' targets, subframes share their
48
+ * parent's id space). 'Aborted' (not BlockedByClient) fails the request but
49
+ * keeps the old page instead of swapping in a chrome-error:// page.
50
+ * Call once per CDP connection, before the first navigation.
51
+ * @param {object} cdp - root CDP client
52
+ * @param {SiteLock} lock
53
+ */
54
+ export function applySiteLockCDP(cdp: object, lock: SiteLock): Promise<void>;
55
+ /**
56
+ * Firefox/BiDi: build the "is this paused request a locked top-level load?"
57
+ * check that blocklist-firefox.js's single intercept handler calls (two
58
+ * catch-all handlers on one paused request would race — one continues before
59
+ * the other fails). A request is a top-level document load when it carries a
60
+ * navigation id and its context has no parent. Context ids are tracked from
61
+ * contextCreated and refreshed from getTree when an unknown one shows up, so a
62
+ * popup whose create event lags its first request can't slip through; one that
63
+ * is still unknown after the refresh is treated as top-level (fail closed).
64
+ * Redirect hops arrive as their own beforeRequestSent, so each is checked.
65
+ * @param {object} bidi - BiDi client
66
+ * @param {SiteLock} lock
67
+ * @returns {Promise<(e: object) => Promise<boolean>>} true = fail this request
68
+ */
69
+ export function createFirefoxLockCheck(bidi: object, lock: SiteLock): Promise<(e: object) => Promise<boolean>>;
70
+ export type SiteLock = ReturnType<typeof createSiteLock>;