@rezkam/browser-tools 0.2.0 → 0.3.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/README.md +33 -1
- package/bin/browser-tools.mjs +12 -0
- package/package.json +4 -3
- package/scripts/cdp-common.mjs +309 -0
- package/scripts/cdp-event-capture.mjs +139 -0
- package/scripts/cdp-recording-state.mjs +160 -0
- package/scripts/cdp.mjs +111 -0
- package/scripts/extract-har.mjs +227 -0
- package/scripts/gif-recorder.mjs +451 -0
- package/scripts/har-capture.mjs +485 -0
- package/scripts/record-cdp.mjs +261 -0
- package/scripts/record-gif.mjs +234 -0
- package/scripts/record-har.mjs +270 -0
- package/scripts/review-gif.mjs +203 -0
package/README.md
CHANGED
|
@@ -22,6 +22,12 @@ npm install -g @rezkam/browser-tools
|
|
|
22
22
|
|
|
23
23
|
This installs a global `browser-tools` command (via the package's `bin` entry) and, for programmatic use, exports the browser control module. If you would rather not install it globally, run any command through `npx @rezkam/browser-tools <subcommand>` instead.
|
|
24
24
|
|
|
25
|
+
GIF recording and review also require ffmpeg and its ffprobe tool:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
brew install ffmpeg
|
|
29
|
+
```
|
|
30
|
+
|
|
25
31
|
## CLI
|
|
26
32
|
|
|
27
33
|
Each subcommand dispatches to the matching script unchanged; flags are the same as the underlying script.
|
|
@@ -33,6 +39,17 @@ browser-tools status --port <reported port> # report whether it's running
|
|
|
33
39
|
browser-tools nav https://example.com --port <reported port>
|
|
34
40
|
browser-tools eval 'document.title' --port <reported port>
|
|
35
41
|
browser-tools screenshot --full --port <reported port>
|
|
42
|
+
browser-tools record-gif start --output "$PWD/login_process.gif" --port <reported port>
|
|
43
|
+
# Perform the multi-step interaction.
|
|
44
|
+
browser-tools record-gif stop --port <reported port>
|
|
45
|
+
browser-tools review-gif "$PWD/login_process.gif"
|
|
46
|
+
browser-tools record-har start --output "$PWD/checkout_api_network.har" --preset api --port <reported port>
|
|
47
|
+
# Perform the browser interaction, then stop and extract a non-executable recipe.
|
|
48
|
+
browser-tools record-har stop --port <reported port>
|
|
49
|
+
browser-tools extract-har "$PWD/checkout_api_network.har"
|
|
50
|
+
browser-tools record-cdp start --output "$PWD/checkout_network_events.jsonl" --domain Network --event 'Network.*' --port <reported port>
|
|
51
|
+
browser-tools record-cdp stop --port <reported port>
|
|
52
|
+
browser-tools cdp call Runtime.evaluate --params '{"expression":"document.title"}' --port <reported port>
|
|
36
53
|
browser-tools pick "Click the price" --port <reported port>
|
|
37
54
|
browser-tools scrape-page --port <reported port>
|
|
38
55
|
browser-tools extract-article --chars 6000 --port <reported port>
|
|
@@ -55,11 +72,26 @@ import { connectBrowser, activePage, withBrowser } from '@rezkam/browser-tools';
|
|
|
55
72
|
- Headless (`--headless`) runs full Chrome (`--headless=new`), not the legacy no-extensions engine, so profile, cookies, and extensions load the same as a windowed launch.
|
|
56
73
|
- Profile Sync excludes the Google identity from a copied profile by default, so a clone cannot log your main Chrome out of Google; pass `--include-google` only for Google-backed workflows.
|
|
57
74
|
- Every managed browser is owned by a token printed at `start`; `stop` refuses to kill a browser it does not own, another agent's browser, or your main Chrome.
|
|
75
|
+
- GIF recording requires an explicit action-specific output name. `start` captures pre-action frames before returning, and `stop` captures post-action frames before finalizing the GIF.
|
|
76
|
+
- `review-gif` probes frame count, duration, frame rate, and dimensions, then creates a sampled contact sheet and JSON report under the GIF's owner-only `.gif-review/` directory.
|
|
77
|
+
- `record-har` captures owner-protected filtered active-tab HTTP traffic as private HAR 1.2. `extract-har` derives a compact chronological recipe without executing requests. WebSocket handshakes and frames require `record-cdp`.
|
|
78
|
+
- `record-cdp` writes selected raw protocol events as private JSONL. `cdp call` sends one owner-protected active-tab method while blocking known managed-lifecycle bypasses.
|
|
79
|
+
- HAR, recipes, raw CDP events, and direct results preserve exact debugging evidence by default. Add `--redact` to filter sensitive-looking values. Capture files are owner-only `0600`, not encrypted.
|
|
58
80
|
- Config, cache, and artifact directories default to `~/.agents/browser-tools/config.json`, `~/.cache/pi-browser-tools`, and `/tmp`, overridable via `BROWSER_TOOLS_CONFIG_DIR`, `BROWSER_TOOLS_CACHE_DIR`, `BROWSER_TOOLS_ARTIFACT_DIR`, `BROWSER_TOOLS_CHROME_SOURCE_DIR`, and `BROWSER_TOOLS_CHROME_BIN`.
|
|
59
|
-
- Requires macOS Chrome and Node.js 20+.
|
|
81
|
+
- Requires macOS Chrome and Node.js 20+. GIF recording and review require ffmpeg and ffprobe.
|
|
60
82
|
|
|
61
83
|
For the full behavior reference (profile sync internals, ownership rules, stop safety checks, gotchas), see the skill docs in the source repository: [SKILL.md](https://github.com/rezkam/boring-but-good/blob/main/browser-tools/SKILL.md) and [references/browser-control.md](https://github.com/rezkam/boring-but-good/blob/main/browser-tools/references/browser-control.md).
|
|
62
84
|
|
|
85
|
+
## Testing
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
npm test # Fast unit and CLI contract tests
|
|
89
|
+
npm run test:e2e # Real headless Chrome and ffmpeg GIF interaction test
|
|
90
|
+
npm run validate # Both suites
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The E2E tests use real Chrome, ffmpeg, and ffprobe against local isolated fixtures. GIF tests validate recording, private output, and contact-sheet review. Network tests validate raw filtered HAR capture, optional recipe redaction, raw wildcard CDP events, direct CDP calls, owner-token refusal, private file modes, hard event limits, and lifecycle-method blocking. They do not use a live account or external server.
|
|
94
|
+
|
|
63
95
|
## License
|
|
64
96
|
|
|
65
97
|
Apache-2.0
|
package/bin/browser-tools.mjs
CHANGED
|
@@ -13,6 +13,12 @@
|
|
|
13
13
|
* browser-tools nav <url> [--new] [--port <n>]
|
|
14
14
|
* browser-tools eval '<javascript>' [--port <n>]
|
|
15
15
|
* browser-tools screenshot [--full] [--port <n>]
|
|
16
|
+
* browser-tools record-gif start|status|stop [options]
|
|
17
|
+
* browser-tools review-gif <meaningful.gif> [options]
|
|
18
|
+
* browser-tools record-har start|status|stop [options]
|
|
19
|
+
* browser-tools extract-har <capture.har> [options]
|
|
20
|
+
* browser-tools record-cdp start|status|stop [options]
|
|
21
|
+
* browser-tools cdp call <Domain.method> [options]
|
|
16
22
|
* browser-tools pick "<instruction>" [--port <n>]
|
|
17
23
|
* browser-tools scrape-page [--port <n>]
|
|
18
24
|
* browser-tools extract-article [--chars <n>] [--port <n>]
|
|
@@ -33,6 +39,12 @@ const COMMANDS = {
|
|
|
33
39
|
nav: 'nav.mjs',
|
|
34
40
|
eval: 'eval.mjs',
|
|
35
41
|
screenshot: 'screenshot.mjs',
|
|
42
|
+
'record-gif': 'record-gif.mjs',
|
|
43
|
+
'review-gif': 'review-gif.mjs',
|
|
44
|
+
'record-har': 'record-har.mjs',
|
|
45
|
+
'extract-har': 'extract-har.mjs',
|
|
46
|
+
'record-cdp': 'record-cdp.mjs',
|
|
47
|
+
cdp: 'cdp.mjs',
|
|
36
48
|
pick: 'pick.mjs',
|
|
37
49
|
'scrape-page': 'scrape-page.mjs',
|
|
38
50
|
'extract-article': 'extract-article.mjs',
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rezkam/browser-tools",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Sandboxed, owner-token-protected Chrome automation for AI agents:
|
|
3
|
+
"version": "0.3.0",
|
|
4
|
+
"description": "Sandboxed, owner-token-protected Chrome automation for AI agents: control pages, record and review GIFs, capture HAR and raw CDP events, send CDP calls, and manage Chrome profiles.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "Apache-2.0",
|
|
7
7
|
"repository": {
|
|
@@ -32,8 +32,9 @@
|
|
|
32
32
|
},
|
|
33
33
|
"scripts": {
|
|
34
34
|
"test": "node --test test/*.mjs",
|
|
35
|
+
"test:e2e": "node --test --test-concurrency=1 test/e2e/*.test.mjs",
|
|
35
36
|
"coverage": "node --test --experimental-test-coverage test/*.mjs",
|
|
36
|
-
"validate": "npm test"
|
|
37
|
+
"validate": "npm test && npm run test:e2e"
|
|
37
38
|
},
|
|
38
39
|
"dependencies": {
|
|
39
40
|
"puppeteer-core": "^24.42.0"
|
|
@@ -0,0 +1,309 @@
|
|
|
1
|
+
import {
|
|
2
|
+
chmodSync,
|
|
3
|
+
closeSync,
|
|
4
|
+
existsSync,
|
|
5
|
+
mkdirSync,
|
|
6
|
+
openSync,
|
|
7
|
+
renameSync,
|
|
8
|
+
writeFileSync,
|
|
9
|
+
} from 'node:fs';
|
|
10
|
+
import { basename, dirname, extname, parse, resolve } from 'node:path';
|
|
11
|
+
import { activePage, connectBrowser } from './browser-control.mjs';
|
|
12
|
+
|
|
13
|
+
export const HAR_RESOURCE_TYPES = [
|
|
14
|
+
'Document',
|
|
15
|
+
'Stylesheet',
|
|
16
|
+
'Image',
|
|
17
|
+
'Media',
|
|
18
|
+
'Font',
|
|
19
|
+
'Script',
|
|
20
|
+
'TextTrack',
|
|
21
|
+
'XHR',
|
|
22
|
+
'Fetch',
|
|
23
|
+
'Prefetch',
|
|
24
|
+
'EventSource',
|
|
25
|
+
'Manifest',
|
|
26
|
+
'SignedExchange',
|
|
27
|
+
'Ping',
|
|
28
|
+
'CSPViolationReport',
|
|
29
|
+
'Preflight',
|
|
30
|
+
'FedCM',
|
|
31
|
+
'Other',
|
|
32
|
+
];
|
|
33
|
+
|
|
34
|
+
export const HAR_RESOURCE_PRESETS = {
|
|
35
|
+
api: ['XHR', 'Fetch', 'Preflight', 'EventSource'],
|
|
36
|
+
page: ['Document', 'Script', 'Stylesheet', 'XHR', 'Fetch'],
|
|
37
|
+
all: [...HAR_RESOURCE_TYPES],
|
|
38
|
+
};
|
|
39
|
+
|
|
40
|
+
export const BLOCKED_CDP_METHODS = new Set([
|
|
41
|
+
'Browser.close',
|
|
42
|
+
'Browser.crash',
|
|
43
|
+
'Page.close',
|
|
44
|
+
'Page.crash',
|
|
45
|
+
'Target.attachToBrowserTarget',
|
|
46
|
+
'Target.closeTarget',
|
|
47
|
+
'Target.detachFromTarget',
|
|
48
|
+
'Target.disposeBrowserContext',
|
|
49
|
+
'Target.sendMessageToTarget',
|
|
50
|
+
]);
|
|
51
|
+
|
|
52
|
+
const SENSITIVE_NAME = /(?:^|[-_])(?:authorization|proxy[-_]?authorization|cookie|set[-_]?cookie|api[-_]?key|access[-_]?token|refresh[-_]?token|id[-_]?token|token|secret|password|passwd|session|csrf|xsrf)(?:$|[-_])/i;
|
|
53
|
+
const URL_HEADER_NAME = /^(?:content-location|location|origin|referer|referrer)$/i;
|
|
54
|
+
const GENERIC_CAPTURE_STEMS = new Set(['capture', 'network', 'output', 'recording', 'trace', 'untitled', 'test']);
|
|
55
|
+
|
|
56
|
+
export function validateCdpMethod(value, { allowBlocked = false } = {}) {
|
|
57
|
+
if (!value || !/^[A-Z][A-Za-z0-9]*\.[a-zA-Z][A-Za-z0-9]*$/.test(value)) {
|
|
58
|
+
throw new Error(`Invalid CDP method: ${value || '<missing>'}. Expected Domain.method`);
|
|
59
|
+
}
|
|
60
|
+
if (!allowBlocked && BLOCKED_CDP_METHODS.has(value)) {
|
|
61
|
+
throw new Error(`CDP method ${value} is blocked because it bypasses managed-browser lifecycle safety`);
|
|
62
|
+
}
|
|
63
|
+
return value;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
export function rawOptionValues(args, name) {
|
|
67
|
+
const values = [];
|
|
68
|
+
for (let index = 0; index < args.length; index += 1) {
|
|
69
|
+
if (args[index] !== name) continue;
|
|
70
|
+
const value = args[index + 1];
|
|
71
|
+
if (value === undefined || value.startsWith('--')) throw new Error(`Missing value after ${name}`);
|
|
72
|
+
values.push(String(value));
|
|
73
|
+
index += 1;
|
|
74
|
+
}
|
|
75
|
+
return values;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
export function optionValues(args, name) {
|
|
79
|
+
return rawOptionValues(args, name)
|
|
80
|
+
.flatMap((value) => value.split(',').map((part) => part.trim()).filter(Boolean));
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
export function patternOptionValues(args, name) {
|
|
84
|
+
return rawOptionValues(args, name).map((value) => value.trim()).filter(Boolean);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
export function normalizeResourceTypes(values, { allowEmpty = true } = {}) {
|
|
88
|
+
if (!values.length && allowEmpty) return [];
|
|
89
|
+
const canonical = new Map(HAR_RESOURCE_TYPES.map((type) => [type.toLowerCase(), type]));
|
|
90
|
+
return [...new Set(values.map((value) => {
|
|
91
|
+
const type = canonical.get(String(value).toLowerCase());
|
|
92
|
+
if (!type) throw new Error(`Unsupported HAR resource type: ${value}. Expected one of: ${HAR_RESOURCE_TYPES.join(', ')}`);
|
|
93
|
+
return type;
|
|
94
|
+
}))];
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
export function resourceTypesForPreset(preset = 'all') {
|
|
98
|
+
const types = HAR_RESOURCE_PRESETS[String(preset).toLowerCase()];
|
|
99
|
+
if (!types) throw new Error(`Unknown capture preset: ${preset}. Expected api, page, or all`);
|
|
100
|
+
return [...types];
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
export function globToRegExp(pattern) {
|
|
104
|
+
let source = '';
|
|
105
|
+
for (const character of String(pattern)) {
|
|
106
|
+
if (character === '*') source += '.*';
|
|
107
|
+
else if (character === '?') source += '.';
|
|
108
|
+
else source += character.replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
|
|
109
|
+
}
|
|
110
|
+
return new RegExp(`^${source}$`, 'i');
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
export function matchesPatterns(value, includes = [], excludes = []) {
|
|
114
|
+
const text = String(value ?? '');
|
|
115
|
+
if (excludes.some((pattern) => globToRegExp(pattern).test(text))) return false;
|
|
116
|
+
return !includes.length || includes.some((pattern) => globToRegExp(pattern).test(text));
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
export function parseStatusSelectors(values) {
|
|
120
|
+
return values.map((value) => {
|
|
121
|
+
const match = String(value).match(/^(\d{3})(?:-(\d{3}))?$/);
|
|
122
|
+
if (!match) throw new Error(`Invalid status selector: ${value}. Use a code or range such as 200-299`);
|
|
123
|
+
const start = Number(match[1]);
|
|
124
|
+
const end = Number(match[2] || match[1]);
|
|
125
|
+
if (end < start) throw new Error(`Invalid status selector range: ${value}`);
|
|
126
|
+
return { start, end };
|
|
127
|
+
});
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
export function matchesStatus(status, includes = [], excludes = []) {
|
|
131
|
+
const number = Number(status);
|
|
132
|
+
const matches = (selector) => number >= selector.start && number <= selector.end;
|
|
133
|
+
if (excludes.some(matches)) return false;
|
|
134
|
+
return !includes.length || includes.some(matches);
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
export function redactUrl(value, { includeSensitive = false } = {}) {
|
|
138
|
+
if (includeSensitive) return value;
|
|
139
|
+
const text = String(value);
|
|
140
|
+
try {
|
|
141
|
+
const url = new URL(text);
|
|
142
|
+
for (const key of [...url.searchParams.keys()]) {
|
|
143
|
+
if (isSensitiveName(key)) url.searchParams.set(key, '<redacted>');
|
|
144
|
+
}
|
|
145
|
+
return url.toString();
|
|
146
|
+
} catch {
|
|
147
|
+
const hashIndex = text.indexOf('#');
|
|
148
|
+
const beforeHash = hashIndex >= 0 ? text.slice(0, hashIndex) : text;
|
|
149
|
+
const hash = hashIndex >= 0 ? text.slice(hashIndex) : '';
|
|
150
|
+
const queryIndex = beforeHash.indexOf('?');
|
|
151
|
+
if (queryIndex < 0) return value;
|
|
152
|
+
const params = new URLSearchParams(beforeHash.slice(queryIndex + 1));
|
|
153
|
+
let changed = false;
|
|
154
|
+
for (const key of [...params.keys()]) {
|
|
155
|
+
if (isSensitiveName(key)) {
|
|
156
|
+
params.set(key, '<redacted>');
|
|
157
|
+
changed = true;
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
return changed ? `${beforeHash.slice(0, queryIndex)}?${params}${hash}` : value;
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
export function isSensitiveName(name) {
|
|
165
|
+
const normalized = String(name).replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
|
|
166
|
+
return SENSITIVE_NAME.test(normalized);
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
export function redactSensitive(value, { includeSensitive = false, parentKey = '' } = {}) {
|
|
170
|
+
if (includeSensitive || value === null || value === undefined) return value;
|
|
171
|
+
if (Array.isArray(value)) {
|
|
172
|
+
return value.map((item) => redactSensitive(item, { includeSensitive, parentKey }));
|
|
173
|
+
}
|
|
174
|
+
if (typeof value !== 'object') return value;
|
|
175
|
+
|
|
176
|
+
const result = {};
|
|
177
|
+
for (const [key, child] of Object.entries(value)) {
|
|
178
|
+
if (/headersText$/i.test(key) && typeof child === 'string') {
|
|
179
|
+
result[key] = '<redacted>';
|
|
180
|
+
continue;
|
|
181
|
+
}
|
|
182
|
+
if (/(?:^|_)(?:url|documenturl|redirecturl)$/i.test(key) && typeof child === 'string') {
|
|
183
|
+
result[key] = redactUrl(child, { includeSensitive });
|
|
184
|
+
continue;
|
|
185
|
+
}
|
|
186
|
+
if (/cookies?/i.test(key) && child && typeof child === 'object') {
|
|
187
|
+
result[key] = redactSensitive(child, { includeSensitive, parentKey: 'cookies' });
|
|
188
|
+
continue;
|
|
189
|
+
}
|
|
190
|
+
if (isSensitiveName(key)) {
|
|
191
|
+
result[key] = '<redacted>';
|
|
192
|
+
continue;
|
|
193
|
+
}
|
|
194
|
+
if (URL_HEADER_NAME.test(key) && typeof child === 'string') {
|
|
195
|
+
result[key] = redactUrl(child, { includeSensitive });
|
|
196
|
+
continue;
|
|
197
|
+
}
|
|
198
|
+
if (key === 'value' && isSensitiveName(value.name)) {
|
|
199
|
+
result[key] = '<redacted>';
|
|
200
|
+
continue;
|
|
201
|
+
}
|
|
202
|
+
if (key === 'value' && URL_HEADER_NAME.test(value.name) && typeof child === 'string') {
|
|
203
|
+
result[key] = redactUrl(child, { includeSensitive });
|
|
204
|
+
continue;
|
|
205
|
+
}
|
|
206
|
+
if (key === 'value' && /cookies?|associatedcookies/i.test(parentKey)) {
|
|
207
|
+
result[key] = '<redacted>';
|
|
208
|
+
continue;
|
|
209
|
+
}
|
|
210
|
+
if (key === 'payloadData' && /websocket/i.test(parentKey)) {
|
|
211
|
+
result[key] = '<redacted>';
|
|
212
|
+
continue;
|
|
213
|
+
}
|
|
214
|
+
result[key] = redactSensitive(child, { includeSensitive, parentKey: key });
|
|
215
|
+
}
|
|
216
|
+
return result;
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
export function redactHeaders(headers = {}, { includeSensitive = false } = {}) {
|
|
220
|
+
return Object.entries(headers).map(([name, value]) => ({
|
|
221
|
+
name,
|
|
222
|
+
value: includeSensitive
|
|
223
|
+
? String(value)
|
|
224
|
+
: (isSensitiveName(name)
|
|
225
|
+
? '<redacted>'
|
|
226
|
+
: (URL_HEADER_NAME.test(name) ? redactUrl(value) : String(value))),
|
|
227
|
+
}));
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
export function redactBodyText(text, mimeType = '', { includeSensitive = false } = {}) {
|
|
231
|
+
if (includeSensitive || text === undefined || text === null) return text;
|
|
232
|
+
const value = String(text);
|
|
233
|
+
const normalizedMime = String(mimeType).toLowerCase();
|
|
234
|
+
if (normalizedMime.includes('json') || /^[\s]*[\[{]/.test(value)) {
|
|
235
|
+
try {
|
|
236
|
+
return JSON.stringify(redactSensitive(JSON.parse(value)));
|
|
237
|
+
} catch {
|
|
238
|
+
return '<redacted: malformed JSON>';
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
const looksFormEncoded = normalizedMime.includes('application/x-www-form-urlencoded')
|
|
242
|
+
|| value.split('&').every((part) => /^[^=&\s]+=[^&]*$/.test(part));
|
|
243
|
+
if (looksFormEncoded) {
|
|
244
|
+
const params = new URLSearchParams(value);
|
|
245
|
+
let changed = false;
|
|
246
|
+
for (const key of [...params.keys()]) {
|
|
247
|
+
if (isSensitiveName(key)) {
|
|
248
|
+
params.set(key, '<redacted>');
|
|
249
|
+
changed = true;
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
return changed ? params.toString() : value;
|
|
253
|
+
}
|
|
254
|
+
return value;
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
export function openPrivateFile(file, flags) {
|
|
258
|
+
const fd = openSync(file, flags, 0o600);
|
|
259
|
+
try {
|
|
260
|
+
chmodSync(file, 0o600);
|
|
261
|
+
return fd;
|
|
262
|
+
} catch (error) {
|
|
263
|
+
closeSync(fd);
|
|
264
|
+
throw new Error(`Could not make capture output private: ${file}: ${error.message}`);
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
export function privateOutputPath(value, extension, { overwrite = false, cwd = process.cwd() } = {}) {
|
|
269
|
+
if (!value || value === true || !String(value).trim()) {
|
|
270
|
+
throw new Error(`Missing --output. Use a meaningful interaction-specific .${extension} filename`);
|
|
271
|
+
}
|
|
272
|
+
const path = resolve(cwd, String(value));
|
|
273
|
+
if (extname(path).toLowerCase() !== `.${extension.toLowerCase()}`) {
|
|
274
|
+
throw new Error(`Capture output must end in .${extension}: ${value}`);
|
|
275
|
+
}
|
|
276
|
+
const stem = parse(basename(path)).name.toLowerCase().replace(/[^a-z0-9]/g, '');
|
|
277
|
+
if (GENERIC_CAPTURE_STEMS.has(stem)) {
|
|
278
|
+
throw new Error(`Capture output name is too generic: ${basename(path)}. Describe the interaction, for example checkout_api_network.${extension}`);
|
|
279
|
+
}
|
|
280
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
281
|
+
if (existsSync(path) && !overwrite) {
|
|
282
|
+
throw new Error(`Capture output already exists: ${path}. Choose another meaningful name or pass --overwrite`);
|
|
283
|
+
}
|
|
284
|
+
return path;
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
export function writePrivateJson(file, value) {
|
|
288
|
+
const temporary = `${file}.${process.pid}.tmp`;
|
|
289
|
+
writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
|
|
290
|
+
renameSync(temporary, file);
|
|
291
|
+
try {
|
|
292
|
+
chmodSync(file, 0o600);
|
|
293
|
+
} catch {
|
|
294
|
+
// Best effort. Capture output may contain private request data.
|
|
295
|
+
}
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
export async function withPageCdpSession(port, ownerToken, callback) {
|
|
299
|
+
const browser = await connectBrowser(port, { ownerToken });
|
|
300
|
+
let session;
|
|
301
|
+
try {
|
|
302
|
+
const page = await activePage(browser);
|
|
303
|
+
session = await page.createCDPSession();
|
|
304
|
+
return await callback({ browser, page, session });
|
|
305
|
+
} finally {
|
|
306
|
+
if (session && !session.detached) await session.detach().catch(() => {});
|
|
307
|
+
browser.disconnect();
|
|
308
|
+
}
|
|
309
|
+
}
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
import { hasFlag, parsePositiveIntegerOption, sleep } from './browser-control.mjs';
|
|
2
|
+
import {
|
|
3
|
+
matchesPatterns,
|
|
4
|
+
optionValues,
|
|
5
|
+
rawOptionValues,
|
|
6
|
+
redactBodyText,
|
|
7
|
+
redactSensitive,
|
|
8
|
+
validateCdpMethod,
|
|
9
|
+
} from './cdp-common.mjs';
|
|
10
|
+
|
|
11
|
+
export const DEFAULT_CDP_POST_WAIT_MS = 500;
|
|
12
|
+
export const DEFAULT_CDP_MAX_DURATION_SECONDS = 300;
|
|
13
|
+
export const DEFAULT_CDP_MAX_EVENTS = 100000;
|
|
14
|
+
|
|
15
|
+
function validateDomain(domain) {
|
|
16
|
+
if (!/^[A-Z][A-Za-z0-9]*$/.test(domain)) throw new Error(`Invalid CDP domain: ${domain}`);
|
|
17
|
+
return domain;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
function validateEventPattern(pattern) {
|
|
21
|
+
if (!/^[A-Z*][A-Za-z0-9*?]*\.[A-Za-z0-9*?]+$/.test(pattern)) {
|
|
22
|
+
throw new Error(`Invalid CDP event pattern: ${pattern}. Use Domain.event or Domain.*`);
|
|
23
|
+
}
|
|
24
|
+
return pattern;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function parseSetupCommand(value) {
|
|
28
|
+
let command;
|
|
29
|
+
if (String(value).trim().startsWith('{')) {
|
|
30
|
+
try {
|
|
31
|
+
command = JSON.parse(value);
|
|
32
|
+
} catch (error) {
|
|
33
|
+
throw new Error(`Invalid --setup JSON: ${error.message}`);
|
|
34
|
+
}
|
|
35
|
+
} else {
|
|
36
|
+
command = { method: value, params: {} };
|
|
37
|
+
}
|
|
38
|
+
const method = validateCdpMethod(command.method);
|
|
39
|
+
const params = command.params ?? {};
|
|
40
|
+
if (!params || typeof params !== 'object' || Array.isArray(params)) {
|
|
41
|
+
throw new Error(`CDP setup params for ${method} must be a JSON object`);
|
|
42
|
+
}
|
|
43
|
+
return { method, params };
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
export function parseCdpEventCaptureOptions(args) {
|
|
47
|
+
const eventPatterns = optionValues(args, '--event').map(validateEventPattern);
|
|
48
|
+
const excludedEventPatterns = optionValues(args, '--exclude-event').map(validateEventPattern);
|
|
49
|
+
const explicitDomains = optionValues(args, '--domain').map(validateDomain);
|
|
50
|
+
const inferredDomains = eventPatterns
|
|
51
|
+
.map((pattern) => pattern.split('.')[0])
|
|
52
|
+
.filter((domain) => !domain.includes('*') && !domain.includes('?'))
|
|
53
|
+
.map(validateDomain);
|
|
54
|
+
const domains = [...new Set([...explicitDomains, ...inferredDomains])];
|
|
55
|
+
if (!domains.length) domains.push('Network');
|
|
56
|
+
const skippedDomainEnables = optionValues(args, '--skip-enable').map(validateDomain);
|
|
57
|
+
const setupCommands = rawOptionValues(args, '--setup').map(parseSetupCommand);
|
|
58
|
+
|
|
59
|
+
return {
|
|
60
|
+
domains,
|
|
61
|
+
skippedDomainEnables,
|
|
62
|
+
setupCommands,
|
|
63
|
+
eventPatterns: eventPatterns.length ? eventPatterns : domains.map((domain) => `${domain}.*`),
|
|
64
|
+
excludedEventPatterns,
|
|
65
|
+
postWaitMs: parsePositiveIntegerOption(args, '--post-wait-ms', DEFAULT_CDP_POST_WAIT_MS),
|
|
66
|
+
maxDurationSeconds: parsePositiveIntegerOption(args, '--max-duration', DEFAULT_CDP_MAX_DURATION_SECONDS),
|
|
67
|
+
maxEvents: parsePositiveIntegerOption(args, '--max-events', DEFAULT_CDP_MAX_EVENTS),
|
|
68
|
+
redact: hasFlag(args, '--redact'),
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
function headerValue(headers, wanted) {
|
|
73
|
+
const match = Object.entries(headers || {}).find(([name]) => name.toLowerCase() === wanted.toLowerCase());
|
|
74
|
+
return match ? String(match[1]) : '';
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
export function sanitizeCdpEvent(method, params, { redact = false } = {}) {
|
|
78
|
+
if (!redact) return params;
|
|
79
|
+
const sanitized = redactSensitive(params);
|
|
80
|
+
if (method === 'Network.requestWillBeSent') {
|
|
81
|
+
if (sanitized.request?.postData !== undefined) {
|
|
82
|
+
const mimeType = headerValue(sanitized.request.headers, 'content-type');
|
|
83
|
+
sanitized.request.postData = redactBodyText(sanitized.request.postData, mimeType);
|
|
84
|
+
}
|
|
85
|
+
if (sanitized.request?.postDataEntries !== undefined) sanitized.request.postDataEntries = '<redacted>';
|
|
86
|
+
}
|
|
87
|
+
if (method === 'Network.webSocketFrameSent' || method === 'Network.webSocketFrameReceived') {
|
|
88
|
+
if (sanitized.response?.payloadData !== undefined) sanitized.response.payloadData = '<redacted>';
|
|
89
|
+
}
|
|
90
|
+
if (method === 'Network.eventSourceMessageReceived' && sanitized.data !== undefined) {
|
|
91
|
+
sanitized.data = '<redacted>';
|
|
92
|
+
}
|
|
93
|
+
return sanitized;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
export async function runCdpEventCapture({
|
|
97
|
+
session,
|
|
98
|
+
options,
|
|
99
|
+
shouldStop,
|
|
100
|
+
writeEvent,
|
|
101
|
+
onPhase = () => {},
|
|
102
|
+
}) {
|
|
103
|
+
let eventCount = 0;
|
|
104
|
+
const startedMonotonic = performance.now();
|
|
105
|
+
const onAnyEvent = (method, params) => {
|
|
106
|
+
if (eventCount >= options.maxEvents) return;
|
|
107
|
+
if (typeof method !== 'string') return;
|
|
108
|
+
if (!matchesPatterns(method, options.eventPatterns, options.excludedEventPatterns)) return;
|
|
109
|
+
writeEvent({
|
|
110
|
+
timestamp: new Date().toISOString(),
|
|
111
|
+
elapsed_ms: Number((performance.now() - startedMonotonic).toFixed(3)),
|
|
112
|
+
method,
|
|
113
|
+
params: sanitizeCdpEvent(method, params, options),
|
|
114
|
+
});
|
|
115
|
+
eventCount += 1;
|
|
116
|
+
};
|
|
117
|
+
session.on('*', onAnyEvent);
|
|
118
|
+
|
|
119
|
+
for (const domain of options.domains) {
|
|
120
|
+
if (options.skippedDomainEnables.includes(domain)) continue;
|
|
121
|
+
try {
|
|
122
|
+
await session.send(`${domain}.enable`);
|
|
123
|
+
} catch (error) {
|
|
124
|
+
throw new Error(`Could not enable CDP domain ${domain}: ${error.message}. Use --skip-enable ${domain} and --setup when the domain needs a different activation method.`);
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
for (const command of options.setupCommands) {
|
|
128
|
+
await session.send(command.method, command.params);
|
|
129
|
+
}
|
|
130
|
+
await onPhase('recording');
|
|
131
|
+
|
|
132
|
+
const deadline = Date.now() + options.maxDurationSeconds * 1000;
|
|
133
|
+
while (!shouldStop() && Date.now() < deadline && eventCount < options.maxEvents) await sleep(100);
|
|
134
|
+
const reason = shouldStop() ? 'requested' : (eventCount >= options.maxEvents ? 'max-events' : 'max-duration');
|
|
135
|
+
await onPhase('post-wait', reason);
|
|
136
|
+
await sleep(options.postWaitMs);
|
|
137
|
+
session.off('*', onAnyEvent);
|
|
138
|
+
return { reason, eventCount };
|
|
139
|
+
}
|