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.
- package/CHANGELOG.md +58 -0
- package/README.md +32 -1
- package/barebrowse.context.md +10 -5
- package/cli.js +24 -6
- package/commands/barebrowse/SKILL.md +142 -0
- package/commands/barebrowse.md +141 -0
- package/mcp-server.js +78 -9
- package/package.json +2 -1
- package/src/aria.js +5 -0
- package/src/ax-snapshot.js +1 -0
- package/src/bareagent.js +5 -3
- package/src/blocklist-firefox.js +12 -4
- package/src/daemon.js +7 -4
- package/src/data.js +24 -9
- package/src/firefox-page.js +71 -12
- package/src/index.js +127 -24
- package/src/links.js +46 -0
- package/src/navigation.js +54 -0
- package/src/prune.js +11 -3
- package/src/site-lock.js +184 -0
- package/types/aria.d.ts +0 -6
- package/types/blocklist-firefox.d.ts +2 -1
- package/types/data.d.ts +6 -1
- package/types/firefox-page.d.ts +17 -1
- package/types/index.d.ts +22 -3
- package/types/links.d.ts +28 -0
- package/types/navigation.d.ts +56 -0
- package/types/prune.d.ts +2 -0
- package/types/site-lock.d.ts +70 -0
package/src/site-lock.js
ADDED
|
@@ -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
|
|
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;
|
package/types/firefox-page.d.ts
CHANGED
|
@@ -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<
|
|
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<
|
|
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<
|
|
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<
|
|
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()`.
|
package/types/links.d.ts
ADDED
|
@@ -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>;
|