turno-browser 0.3.0 → 0.4.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.
Files changed (94) hide show
  1. package/CHANGELOG.md +98 -0
  2. package/README.md +32 -3
  3. package/dist/act-model.d.ts +85 -0
  4. package/dist/act-model.js +116 -0
  5. package/dist/act.d.ts +37 -0
  6. package/dist/act.js +599 -0
  7. package/dist/api.d.ts +29 -2
  8. package/dist/api.js +29 -2
  9. package/dist/argv.d.ts +16 -2
  10. package/dist/argv.js +100 -3
  11. package/dist/batch.d.ts +5 -0
  12. package/dist/batch.js +3 -3
  13. package/dist/bin/mcp.js +58 -1
  14. package/dist/captcha.d.ts +77 -0
  15. package/dist/captcha.js +333 -0
  16. package/dist/cdp-relay.d.ts +20 -0
  17. package/dist/cdp-relay.js +101 -0
  18. package/dist/chrome-features.d.ts +23 -0
  19. package/dist/chrome-features.js +44 -0
  20. package/dist/diagnose.d.ts +7 -0
  21. package/dist/diagnose.js +61 -6
  22. package/dist/doctor.d.ts +37 -3
  23. package/dist/doctor.js +230 -5
  24. package/dist/engine-attach.d.ts +27 -0
  25. package/dist/engine-attach.js +165 -0
  26. package/dist/engine-camoufox.d.ts +32 -0
  27. package/dist/engine-camoufox.js +270 -0
  28. package/dist/engine-lightpanda.d.ts +72 -0
  29. package/dist/engine-lightpanda.js +292 -0
  30. package/dist/engine.d.ts +63 -11
  31. package/dist/engine.js +104 -28
  32. package/dist/flows.d.ts +127 -0
  33. package/dist/flows.js +294 -0
  34. package/dist/governor.d.ts +42 -7
  35. package/dist/governor.js +82 -32
  36. package/dist/host.d.ts +17 -2
  37. package/dist/host.js +618 -41
  38. package/dist/human-input.d.ts +84 -0
  39. package/dist/human-input.js +443 -0
  40. package/dist/humanize.d.ts +123 -0
  41. package/dist/humanize.js +241 -0
  42. package/dist/identities.js +2 -0
  43. package/dist/idle-timer.d.ts +12 -0
  44. package/dist/idle-timer.js +25 -0
  45. package/dist/index.d.ts +8 -3
  46. package/dist/index.js +5 -1
  47. package/dist/lifecycle.d.ts +9 -1
  48. package/dist/lifecycle.js +9 -1
  49. package/dist/live-client.d.ts +22 -0
  50. package/dist/live-client.js +93 -0
  51. package/dist/live-page.d.ts +11 -0
  52. package/dist/live-page.js +143 -0
  53. package/dist/live-server.d.ts +173 -0
  54. package/dist/live-server.js +640 -0
  55. package/dist/live.d.ts +120 -0
  56. package/dist/live.js +203 -0
  57. package/dist/login-tool.d.ts +13 -0
  58. package/dist/login-tool.js +5 -1
  59. package/dist/login.d.ts +4 -1
  60. package/dist/login.js +11 -2
  61. package/dist/network-chrome.d.ts +74 -0
  62. package/dist/network-chrome.js +178 -0
  63. package/dist/network.d.ts +125 -0
  64. package/dist/network.js +263 -0
  65. package/dist/opt-in-settings.d.ts +69 -0
  66. package/dist/opt-in-settings.js +151 -0
  67. package/dist/recorder.d.ts +88 -0
  68. package/dist/recorder.js +538 -0
  69. package/dist/recordings.d.ts +116 -0
  70. package/dist/recordings.js +474 -0
  71. package/dist/redact.d.ts +7 -0
  72. package/dist/redact.js +18 -0
  73. package/dist/replay.d.ts +20 -0
  74. package/dist/replay.js +382 -0
  75. package/dist/reputation.d.ts +24 -2
  76. package/dist/reputation.js +63 -17
  77. package/dist/session-export.js +1 -1
  78. package/dist/session.d.ts +10 -2
  79. package/dist/session.js +10 -2
  80. package/dist/settings.d.ts +104 -2
  81. package/dist/settings.js +204 -6
  82. package/dist/sharing.d.ts +96 -0
  83. package/dist/sharing.js +269 -0
  84. package/dist/snippet.d.ts +8 -2
  85. package/dist/snippet.js +10 -4
  86. package/dist/tab-locks.d.ts +63 -0
  87. package/dist/tab-locks.js +179 -0
  88. package/dist/tools.d.ts +38 -0
  89. package/dist/tools.js +20 -1
  90. package/dist/tuning.d.ts +14 -0
  91. package/dist/tuning.js +9 -0
  92. package/dist/upstream.d.ts +11 -0
  93. package/npm-shrinkwrap.json +2 -2
  94. package/package.json +1 -1
@@ -0,0 +1,178 @@
1
+ import { execFileSync } from "node:child_process";
2
+ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
3
+ import { dirname, join } from "node:path";
4
+ import { PRIVATE_DIR_MODE, PRIVATE_FILE_MODE, browserPaths as paths } from "turno-core/paths";
5
+ import { findChrome } from "./doctor.js";
6
+ import { CHROME_PROXY_ARGS, OBSERVE_SCRIPT, coherenceProblems, majorOf, reducedUserAgent, resolveProxy, } from "./network.js";
7
+ import { acceptLanguages } from "./settings.js";
8
+ /** Where the launch check and the metadata reading load their page: answered by a route, so nothing reaches the network. */
9
+ const CHECK_URL = "https://turno-check.invalid/";
10
+ const READ_METADATA = `(async () => {
11
+ const d = navigator.userAgentData;
12
+ const h = await d.getHighEntropyValues(["fullVersionList", "platformVersion", "architecture", "model", "bitness", "wow64"]);
13
+ return { brands: d.brands.map((b) => ({ brand: b.brand, version: b.version })), fullVersionList: h.fullVersionList.map((b) => ({ brand: b.brand, version: b.version })),
14
+ platform: d.platform, platformVersion: h.platformVersion, architecture: h.architecture, model: h.model || "", mobile: d.mobile, bitness: h.bitness, wow64: !!h.wow64 };
15
+ })()`;
16
+ /**
17
+ * The client hints metadata this Chrome reports with nothing overriding it: read by a short
18
+ * headless launch (no switch, throwaway profile, a routed page) and kept per Chrome version.
19
+ */
20
+ async function realMetadata(config, env, version) {
21
+ const file = join(paths(env).state, "browser", "chrome-ua", `${version.replace(/[^\w.-]/g, "_")}-${process.platform}-${process.arch}.json`);
22
+ try {
23
+ const cached = JSON.parse(readFileSync(file, "utf8"));
24
+ if (cached.fullVersionList?.length && cached.architecture)
25
+ return cached;
26
+ }
27
+ catch {
28
+ /* not read yet */
29
+ }
30
+ const lo = config.browser.launchOptions;
31
+ const { chromium } = await import("patchright-core");
32
+ const browser = await chromium.launch({
33
+ ...(typeof lo.executablePath === "string"
34
+ ? { executablePath: lo.executablePath }
35
+ : { channel: lo.channel ?? "chrome" }),
36
+ headless: true,
37
+ timeout: 20_000,
38
+ });
39
+ let metadata;
40
+ try {
41
+ const page = await browser.newPage();
42
+ await page.route(CHECK_URL, (route) => route.fulfill({ status: 200, contentType: "text/html", body: "<title>turno</title>" }));
43
+ await page.goto(CHECK_URL, { timeout: 15_000 });
44
+ metadata = (await page.evaluate(READ_METADATA));
45
+ }
46
+ finally {
47
+ await browser.close().catch(() => { });
48
+ }
49
+ if (!metadata.fullVersionList.length || !metadata.architecture)
50
+ throw new Error('userAgent "coherent": this Chrome reports no client hints metadata, so turno cannot present it coherently headless');
51
+ mkdirSync(dirname(file), { recursive: true, mode: PRIVATE_DIR_MODE });
52
+ writeFileSync(file, `${JSON.stringify(metadata, null, 2)}\n`, { mode: PRIVATE_FILE_MODE });
53
+ return metadata;
54
+ }
55
+ const hasArg = (args, flag) => args.some((a) => a === flag || a.startsWith(`${flag}=`));
56
+ /** The installed Chrome's version, for the user agent string a headless Chrome needs. */
57
+ function chromeVersion(config, env) {
58
+ const exe = config.browser.launchOptions.executablePath;
59
+ if (typeof exe === "string") {
60
+ try {
61
+ return /(\d+\.\d+\.\d+\.\d+)/.exec(execFileSync(exe, ["--version"], { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] }))?.[1];
62
+ }
63
+ catch {
64
+ return undefined;
65
+ }
66
+ }
67
+ const channel = config.browser.launchOptions.channel ?? "chrome";
68
+ return channel === "chrome" ? findChrome(env)?.version : undefined;
69
+ }
70
+ export async function chromeNetwork(settings, config, env, secret) {
71
+ const out = { args: [] };
72
+ const userArgs = config.browser.launchOptions.args ?? [];
73
+ if (settings.proxy) {
74
+ if (config.browser.launchOptions.proxy !== undefined || hasArg(userArgs, "--proxy-server"))
75
+ throw new Error("identity.json proxy and a proxy of the server's own (--proxy-server, or the config's launchOptions.proxy) are both set: keep one");
76
+ out.proxy = await resolveProxy(settings.proxy, env, secret);
77
+ out.args.push(...CHROME_PROXY_ARGS.filter((a) => !hasArg(userArgs, a.split("=")[0])));
78
+ }
79
+ if (settings.userAgent === "coherent") {
80
+ if (config.browser.contextOptions?.userAgent !== undefined || hasArg(userArgs, "--user-agent"))
81
+ throw new Error('identity.json userAgent "coherent" and a user agent of the server\'s own (--user-agent, --device, or the config) are both set: keep one');
82
+ // Headed Chrome already sends its own reduced user agent; a headless one says
83
+ // HeadlessChrome, so it gets the headed string for the same version.
84
+ if (config.browser.launchOptions.headless) {
85
+ const version = chromeVersion(config, env);
86
+ const major = majorOf(version);
87
+ if (version === undefined || major === undefined)
88
+ throw new Error('userAgent "coherent" needs the installed Chrome\'s version for a headless browser, and turno could not read it: it supports Google Chrome (the chrome channel) or a Chrome given with an executable path');
89
+ const userAgent = reducedUserAgent(major);
90
+ out.args.push(`--user-agent=${userAgent}`);
91
+ out.pin = { userAgent, metadata: await realMetadata(config, env, version) };
92
+ }
93
+ const languages = acceptLanguages(settings);
94
+ const given = out.pin?.metadata;
95
+ out.verify = {
96
+ ...(languages ? { languages } : {}),
97
+ ...(settings.timezone ? { timezone: settings.timezone } : {}),
98
+ ...(given
99
+ ? {
100
+ high: {
101
+ fullVersionList: given.fullVersionList,
102
+ architecture: given.architecture,
103
+ platformVersion: given.platformVersion,
104
+ },
105
+ }
106
+ : {}),
107
+ };
108
+ }
109
+ return out;
110
+ }
111
+ /** Gives every page of the context the pinned user agent and metadata; `ready` resolves once a page has them. */
112
+ export function pinUserAgent(context, pin) {
113
+ const pending = new WeakMap();
114
+ const apply = (page) => {
115
+ // The session stays attached: Chrome drops a DevTools client's overrides when it detaches.
116
+ // A page that closes first rejects too; only `ready` (the launch check, a tool's new tab)
117
+ // reports it, so a page that did not get the values fails instead of loading without them.
118
+ const done = context
119
+ .newCDPSession(page)
120
+ .then((session) => session.send("Emulation.setUserAgentOverride", { userAgent: pin.userAgent, userAgentMetadata: pin.metadata }))
121
+ .then(() => undefined)
122
+ .catch((error) => {
123
+ throw new Error(`userAgent "coherent": this page did not take the user agent metadata: ${error.message}`);
124
+ });
125
+ done.catch(() => { });
126
+ pending.set(page, done);
127
+ };
128
+ for (const page of context.pages())
129
+ apply(page);
130
+ context.on("page", apply);
131
+ const ready = (page) => pending.get(page) ?? Promise.resolve();
132
+ // A tab a tool opens (browser_tabs) navigates right after newPage resolves: resolve it only
133
+ // once the page has the values, so its first request already carries them.
134
+ const newPage = context.newPage.bind(context);
135
+ context.newPage = async () => {
136
+ const page = await newPage();
137
+ await ready(page);
138
+ return page;
139
+ };
140
+ return { ready };
141
+ }
142
+ /**
143
+ * The launch check of `userAgent: "coherent"`: loads a blank page of its own on an https origin
144
+ * (client hints exist only in a secure context), answered by a route so no request leaves the
145
+ * machine, reads what the page sees and what the request carried, and refuses the browser when
146
+ * anything contradicts the rest, or the user agent names another version than the Chrome that
147
+ * runs. A headed Chrome shows that tab for a moment. The caller closes the browser on a throw.
148
+ */
149
+ export async function verifyCoherence(context, version, expected, pinned) {
150
+ const page = await context.newPage();
151
+ await pinned?.ready(page);
152
+ let observed;
153
+ let sent = {};
154
+ try {
155
+ await page.route(CHECK_URL, async (route) => {
156
+ sent = await route.request().allHeaders();
157
+ await route.fulfill({ status: 200, contentType: "text/html", body: "<title>turno</title>" });
158
+ });
159
+ await page.goto(CHECK_URL, { timeout: 15_000 });
160
+ observed = (await page.evaluate(`(${OBSERVE_SCRIPT})()`));
161
+ }
162
+ finally {
163
+ await page.close().catch(() => { });
164
+ }
165
+ const problems = coherenceProblems(observed, expected);
166
+ const major = majorOf(version);
167
+ const uaMajor = /Chrome\/(\d+)\./.exec(observed.userAgent)?.[1];
168
+ if (major !== undefined && uaMajor !== undefined && Number(uaMajor) !== major)
169
+ problems.push(`the user agent says Chrome ${uaMajor}, but Chrome ${major} runs`);
170
+ if (sent["user-agent"] !== undefined && sent["user-agent"] !== observed.userAgent)
171
+ problems.push("the User-Agent header differs from navigator.userAgent");
172
+ const hinted = sent["sec-ch-ua-platform"];
173
+ if (hinted !== undefined && observed.uaData && hinted !== `"${observed.uaData.platform}"`)
174
+ problems.push(`the Sec-CH-UA-Platform header is ${hinted}, but the page reads ${observed.uaData.platform}`);
175
+ if (problems.length)
176
+ throw new Error(`userAgent "coherent": this Chrome would not present one coherent identity, so turno did not use it: ${problems.join("; ")}`);
177
+ }
178
+ //# sourceMappingURL=network-chrome.js.map
@@ -0,0 +1,125 @@
1
+ import { type SecretStore } from "turno-core/secrets";
2
+ /**
3
+ * Opt-in network and user agent settings of an identity (identity.json format 11), both off by
4
+ * default. They are "not recommended": a real Chrome on the user's own connection is already
5
+ * the most coherent browser a site can see, and these settings can only keep it coherent or
6
+ * break it. The docs say what each one costs.
7
+ *
8
+ * `userAgent: "coherent"` presents the identity as the installed Chrome, as one set, verified
9
+ * at every launch:
10
+ *
11
+ * - the user agent string is Chrome's own reduced one for this OS and the installed major
12
+ * version, so a headless Chrome no longer says `HeadlessChrome` (headed, it is unchanged);
13
+ * - the client hints (`Sec-CH-UA*`, `navigator.userAgentData`: brands, full version list,
14
+ * platform, platform version, architecture) and `navigator.platform` stay Chrome's real ones;
15
+ * - the languages and the time zone are the identity's (`languages`/`locale`, `timezone`) or,
16
+ * without them, the system's.
17
+ *
18
+ * The platform and the Chrome version are never configurable. Measured with Chrome 157: no
19
+ * DevTools override reaches `navigator.platform` in a dedicated worker, and a popup's first
20
+ * request carries the real `Sec-CH-UA-Platform` and platform version, so another platform would
21
+ * be a partial override however it is applied (and WebGL, fonts and TLS would still say the real
22
+ * one). A typed user agent string is refused for the same reason.
23
+ *
24
+ * `proxy` sends the identity's traffic through a proxy. The credentials are never written in
25
+ * identity.json: `password` (and `username`, when it is one) is a `keychain:<item>` reference
26
+ * read from the secret store at launch, and both values join the redactor, so no tool result
27
+ * shows them. WebRTC is kept on the proxy (`disable_non_proxied_udp`), so it does not show the
28
+ * direct address.
29
+ */
30
+ /** The values of `userAgent`. */
31
+ declare const USER_AGENT_MODES: readonly ["coherent"];
32
+ export type UserAgentMode = (typeof USER_AGENT_MODES)[number];
33
+ /** identity.json `proxy`. */
34
+ export interface ProxySettings {
35
+ /** `http://`, `https://`, `socks4://` or `socks5://` with a host and an optional port. */
36
+ server: string;
37
+ /** A user name, or a `keychain:<item>` reference to one. */
38
+ username?: string;
39
+ /** Always a `keychain:<item>` reference. */
40
+ password?: string;
41
+ }
42
+ /** Problems with the format 11 keys alone (combinations with the engine keys: `networkEngineClash`). */
43
+ export declare function networkProblems(v: Record<string, unknown>, out: string[]): void;
44
+ /**
45
+ * Why an engine cannot apply these settings. Attach mode drives the user's own Chrome, whose
46
+ * user agent and network turno does not change; read mode is Lightpanda, which presents its
47
+ * own user agent and was not checked with a proxy; Camoufox is Firefox, which sends no client
48
+ * hints at all, so `userAgent` describes nothing there (a proxy works).
49
+ */
50
+ export declare function networkEngineClash(engine: string, settings: {
51
+ userAgent?: unknown;
52
+ proxy?: unknown;
53
+ }): string | undefined;
54
+ /** A proxy ready for Playwright's `proxy` launch option. */
55
+ export interface ResolvedProxy {
56
+ server: string;
57
+ username?: string;
58
+ password?: string;
59
+ }
60
+ /**
61
+ * Reads the proxy's credentials from the secret store. Every value read is handed to `secret`
62
+ * (the redactor) before anything else sees it, with the `Proxy-Authorization` form Chrome sends
63
+ * for a plain http:// request through the proxy. Throws without the value when an item is
64
+ * missing or the store cannot be read.
65
+ */
66
+ export declare function resolveProxy(proxy: ProxySettings, env: NodeJS.ProcessEnv, secret: (value: string, label: string) => void, store?: SecretStore | undefined): Promise<ResolvedProxy>;
67
+ /**
68
+ * Chrome switches that go with a proxy: WebRTC uses the proxy or no UDP at all, so a page
69
+ * cannot read the direct address through a peer connection.
70
+ */
71
+ export declare const CHROME_PROXY_ARGS: readonly string[];
72
+ /** The same for Firefox (Camoufox): ICE candidates only through the proxy. */
73
+ export declare const FIREFOX_PROXY_PREFS: Readonly<Record<string, boolean>>;
74
+ /**
75
+ * Chrome's own reduced user agent string for this OS and major version, as a headed Chrome
76
+ * sends it (the minor, build and patch are always 0 there).
77
+ */
78
+ export declare function reducedUserAgent(major: number, platform?: NodeJS.Platform): string;
79
+ /** What a page reads, for the launch check. */
80
+ export interface ObservedIdentity {
81
+ userAgent: string;
82
+ platform: string;
83
+ languages: string[];
84
+ timezone: string;
85
+ /** `Intl.DateTimeFormat().resolvedOptions().locale`. */
86
+ intlLocale: string;
87
+ uaData?: {
88
+ brands: {
89
+ brand: string;
90
+ version: string;
91
+ }[];
92
+ platform: string;
93
+ mobile: boolean;
94
+ /** The high entropy values (`getHighEntropyValues`), which a user agent override can blank. */
95
+ high?: HighEntropyValues;
96
+ } | null;
97
+ }
98
+ /** The client hints high entropy values the launch check reads. */
99
+ interface HighEntropyValues {
100
+ fullVersionList: {
101
+ brand: string;
102
+ version: string;
103
+ }[];
104
+ architecture: string;
105
+ platformVersion: string;
106
+ }
107
+ /**
108
+ * What the identity should present: `languages` and `timezone` are what was asked for, else
109
+ * unchecked; `high` is the metadata a headless Chrome was given, which every page must read back.
110
+ */
111
+ export interface ExpectedIdentity {
112
+ languages?: string[];
113
+ timezone?: string;
114
+ high?: HighEntropyValues;
115
+ }
116
+ /**
117
+ * Every contradiction between what a page reads and what the identity presents; empty when
118
+ * the set is coherent. Pure, so the bench and the unit tests use it too.
119
+ */
120
+ export declare function coherenceProblems(o: ObservedIdentity, expected?: ExpectedIdentity): string[];
121
+ /** Runs in a page: what `coherenceProblems` checks. */
122
+ export declare const OBSERVE_SCRIPT = "async () => {\n const d = navigator.userAgentData;\n const high = d ? await d.getHighEntropyValues([\"fullVersionList\", \"architecture\", \"platformVersion\"]) : null;\n return {\n userAgent: navigator.userAgent,\n platform: navigator.platform,\n languages: Array.from(navigator.languages || []),\n timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,\n intlLocale: Intl.DateTimeFormat().resolvedOptions().locale,\n uaData: d\n ? {\n brands: d.brands.map((b) => ({ brand: b.brand, version: b.version })),\n platform: d.platform,\n mobile: d.mobile,\n high: {\n fullVersionList: (high.fullVersionList || []).map((b) => ({ brand: b.brand, version: b.version })),\n architecture: high.architecture || \"\",\n platformVersion: high.platformVersion || \"\",\n },\n }\n : null,\n };\n}";
123
+ /** The installed Chrome's major version from a version string like "157.0.8103.79". */
124
+ export declare function majorOf(version: string | undefined): number | undefined;
125
+ export {};
@@ -0,0 +1,263 @@
1
+ import { secretStore } from "turno-core/secrets";
2
+ /**
3
+ * Opt-in network and user agent settings of an identity (identity.json format 11), both off by
4
+ * default. They are "not recommended": a real Chrome on the user's own connection is already
5
+ * the most coherent browser a site can see, and these settings can only keep it coherent or
6
+ * break it. The docs say what each one costs.
7
+ *
8
+ * `userAgent: "coherent"` presents the identity as the installed Chrome, as one set, verified
9
+ * at every launch:
10
+ *
11
+ * - the user agent string is Chrome's own reduced one for this OS and the installed major
12
+ * version, so a headless Chrome no longer says `HeadlessChrome` (headed, it is unchanged);
13
+ * - the client hints (`Sec-CH-UA*`, `navigator.userAgentData`: brands, full version list,
14
+ * platform, platform version, architecture) and `navigator.platform` stay Chrome's real ones;
15
+ * - the languages and the time zone are the identity's (`languages`/`locale`, `timezone`) or,
16
+ * without them, the system's.
17
+ *
18
+ * The platform and the Chrome version are never configurable. Measured with Chrome 157: no
19
+ * DevTools override reaches `navigator.platform` in a dedicated worker, and a popup's first
20
+ * request carries the real `Sec-CH-UA-Platform` and platform version, so another platform would
21
+ * be a partial override however it is applied (and WebGL, fonts and TLS would still say the real
22
+ * one). A typed user agent string is refused for the same reason.
23
+ *
24
+ * `proxy` sends the identity's traffic through a proxy. The credentials are never written in
25
+ * identity.json: `password` (and `username`, when it is one) is a `keychain:<item>` reference
26
+ * read from the secret store at launch, and both values join the redactor, so no tool result
27
+ * shows them. WebRTC is kept on the proxy (`disable_non_proxied_udp`), so it does not show the
28
+ * direct address.
29
+ */
30
+ /** The values of `userAgent`. */
31
+ const USER_AGENT_MODES = ["coherent"];
32
+ const PROXY_SCHEMES = new Set(["http:", "https:", "socks4:", "socks5:"]);
33
+ const KEYCHAIN = "keychain:";
34
+ const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
35
+ /** Problems with a `proxy.server` value; empty when it is valid. */
36
+ function serverProblems(server) {
37
+ if (typeof server !== "string" || !server.trim())
38
+ return ['proxy.server must be a URL like "http://proxy.example.com:8080"'];
39
+ let url;
40
+ try {
41
+ url = new URL(server);
42
+ }
43
+ catch {
44
+ return [`proxy.server "${server}" is not a URL (like "http://proxy.example.com:8080")`];
45
+ }
46
+ if (!PROXY_SCHEMES.has(url.protocol))
47
+ return ["proxy.server must start with http://, https://, socks4:// or socks5://"];
48
+ if (url.username || url.password)
49
+ return [
50
+ "proxy.server must not carry a user name or password: put the user name in proxy.username and the password in the secret store (proxy.password: keychain:<item>)",
51
+ ];
52
+ if (!url.hostname)
53
+ return ["proxy.server needs a host"];
54
+ if ((url.pathname && url.pathname !== "/") || url.search || url.hash)
55
+ return ["proxy.server is a host and port only, with no path or query"];
56
+ return [];
57
+ }
58
+ /** Problems with the format 11 keys alone (combinations with the engine keys: `networkEngineClash`). */
59
+ export function networkProblems(v, out) {
60
+ if (v.userAgent !== undefined && !USER_AGENT_MODES.includes(v.userAgent)) {
61
+ out.push('userAgent must be "coherent": turno builds the user agent from the installed Chrome and never takes a typed one, which would contradict the client hints, WebGL, fonts and TLS');
62
+ }
63
+ if (v.proxy === undefined)
64
+ return;
65
+ const p = v.proxy;
66
+ if (!isObject(p)) {
67
+ out.push('proxy must be an object like { "server": "http://proxy.example.com:8080" }');
68
+ return;
69
+ }
70
+ out.push(...serverProblems(p.server));
71
+ // A trace keeps the launch options, the proxy password among them; the recorder would delete
72
+ // every trace, so the pair is refused up front instead.
73
+ if (p.password !== undefined && isObject(v.record) && v.record.traces === true)
74
+ out.push("record.traces does not go with a proxy password: a trace keeps the browser's launch options, the password included. Record flows and screenshots, or use a proxy without a password");
75
+ if (p.username !== undefined && (typeof p.username !== "string" || !p.username.trim() || /[\r\n]/.test(p.username)))
76
+ out.push("proxy.username must be a user name or a keychain:<item> reference");
77
+ if (p.password !== undefined) {
78
+ if (typeof p.password !== "string" || !p.password.startsWith(KEYCHAIN) || p.password.length <= KEYCHAIN.length)
79
+ out.push("proxy.password must be a keychain:<item> reference (store it with: turno secret set <item>): identity.json never holds a password");
80
+ }
81
+ if (p.password !== undefined && p.username === undefined)
82
+ out.push("proxy.password needs proxy.username");
83
+ if (p.username !== undefined && p.password === undefined)
84
+ out.push("proxy.username needs proxy.password (a keychain:<item> reference)");
85
+ if (p.username !== undefined &&
86
+ typeof p.server === "string" &&
87
+ /^socks[45]:/.test(p.server) &&
88
+ !serverProblems(p.server).length)
89
+ out.push("Chrome cannot sign in to a SOCKS proxy: use an http:// or https:// proxy for one that needs a password");
90
+ for (const k of Object.keys(p))
91
+ if (!["server", "username", "password"].includes(k))
92
+ out.push(`unknown key "proxy.${k}"`);
93
+ }
94
+ /**
95
+ * Why an engine cannot apply these settings. Attach mode drives the user's own Chrome, whose
96
+ * user agent and network turno does not change; read mode is Lightpanda, which presents its
97
+ * own user agent and was not checked with a proxy; Camoufox is Firefox, which sends no client
98
+ * hints at all, so `userAgent` describes nothing there (a proxy works).
99
+ */
100
+ export function networkEngineClash(engine, settings) {
101
+ const asked = [settings.userAgent !== undefined && "userAgent", settings.proxy !== undefined && "proxy"].filter(Boolean);
102
+ if (!asked.length)
103
+ return undefined;
104
+ if (engine === "attach")
105
+ return `${asked.join(" and ")} ${asked.length > 1 ? "do" : "does"} not go with attach mode: that is your own Chrome, and turno does not change its user agent or network. Drop ${asked.length > 1 ? "them" : "it"}, or drop attach`;
106
+ if (engine === "lightpanda")
107
+ return `${asked.join(" and ")} ${asked.length > 1 ? "do" : "does"} not go with engine "lightpanda": read mode presents Lightpanda's own user agent and was not checked with a proxy. Use engine "chrome"`;
108
+ if (engine === "camoufox" && settings.userAgent !== undefined)
109
+ return 'userAgent does not go with engine "camoufox": Camoufox is Firefox, which sends no client hints, and it presents its own values. Drop userAgent (proxy works with Camoufox)';
110
+ return undefined;
111
+ }
112
+ /**
113
+ * Reads the proxy's credentials from the secret store. Every value read is handed to `secret`
114
+ * (the redactor) before anything else sees it, with the `Proxy-Authorization` form Chrome sends
115
+ * for a plain http:// request through the proxy. Throws without the value when an item is
116
+ * missing or the store cannot be read.
117
+ */
118
+ export async function resolveProxy(proxy, env, secret, store = secretStore(env)) {
119
+ const out = { server: proxy.server };
120
+ if (proxy.username === undefined || proxy.password === undefined)
121
+ return out;
122
+ const read = async (ref, what) => {
123
+ if (!ref.startsWith(KEYCHAIN))
124
+ return ref;
125
+ const item = ref.slice(KEYCHAIN.length);
126
+ if (!store)
127
+ throw new Error(`the proxy ${what} is ${ref}, but this machine has no secret store (macOS Keychain or libsecret)`);
128
+ let value;
129
+ try {
130
+ value = await store.get(item);
131
+ }
132
+ catch {
133
+ throw new Error(`the secret store could not read the proxy ${what} (${ref})`);
134
+ }
135
+ if (value === undefined || value === "")
136
+ throw new Error(`the secret store has no item "${item}" for the proxy ${what} (store it with: turno secret set ${item})`);
137
+ return value;
138
+ };
139
+ const username = await read(proxy.username, "user name");
140
+ const password = await read(proxy.password, "password");
141
+ if (proxy.username.startsWith(KEYCHAIN))
142
+ secret(username, "proxy user name");
143
+ secret(password, "proxy password");
144
+ const basic = Buffer.from(`${username}:${password}`).toString("base64");
145
+ // "password" in the label: a saved trace holding it is deleted (recordings.ts).
146
+ secret(basic, "proxy password, Basic encoded");
147
+ return { ...out, username, password };
148
+ }
149
+ /**
150
+ * Chrome switches that go with a proxy: WebRTC uses the proxy or no UDP at all, so a page
151
+ * cannot read the direct address through a peer connection.
152
+ */
153
+ export const CHROME_PROXY_ARGS = Object.freeze([
154
+ "--force-webrtc-ip-handling-policy=disable_non_proxied_udp",
155
+ ]);
156
+ /** The same for Firefox (Camoufox): ICE candidates only through the proxy. */
157
+ export const FIREFOX_PROXY_PREFS = Object.freeze({
158
+ "media.peerconnection.ice.proxy_only_if_behind_proxy": true,
159
+ "media.peerconnection.ice.default_address_only": true,
160
+ });
161
+ /** The OS tokens of Chrome's reduced user agent string, frozen by Chrome for every version of each OS. */
162
+ const UA_PLATFORM = {
163
+ darwin: "Macintosh; Intel Mac OS X 10_15_7",
164
+ win32: "Windows NT 10.0; Win64; x64",
165
+ linux: "X11; Linux x86_64",
166
+ };
167
+ /**
168
+ * Chrome's own reduced user agent string for this OS and major version, as a headed Chrome
169
+ * sends it (the minor, build and patch are always 0 there).
170
+ */
171
+ export function reducedUserAgent(major, platform = process.platform) {
172
+ const os = UA_PLATFORM[platform] ?? UA_PLATFORM.linux;
173
+ return `Mozilla/5.0 (${os}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${major}.0.0.0 Safari/537.36`;
174
+ }
175
+ /** The `navigator.userAgentData.platform` and `navigator.platform` prefixes for each UA OS token. */
176
+ const PLATFORMS = [
177
+ { ua: /Macintosh/, hints: "macOS", navigator: /^Mac/ },
178
+ { ua: /Windows/, hints: "Windows", navigator: /^Win/ },
179
+ { ua: /CrOS/, hints: "Chrome OS", navigator: /^Linux/ },
180
+ { ua: /Android/, hints: "Android", navigator: /^Linux/ },
181
+ { ua: /X11|Linux/, hints: "Linux", navigator: /^Linux/ },
182
+ ];
183
+ const base = (tag) => tag.split("-")[0].toLowerCase();
184
+ const highEntropyKey = (h) => JSON.stringify([h.fullVersionList.map((b) => `${b.brand} ${b.version}`), h.architecture, h.platformVersion]);
185
+ /**
186
+ * Every contradiction between what a page reads and what the identity presents; empty when
187
+ * the set is coherent. Pure, so the bench and the unit tests use it too.
188
+ */
189
+ export function coherenceProblems(o, expected = {}) {
190
+ const out = [];
191
+ if (/HeadlessChrome/.test(o.userAgent))
192
+ out.push("the user agent says HeadlessChrome");
193
+ const major = /Chrome\/(\d+)\./.exec(o.userAgent)?.[1];
194
+ if (!major)
195
+ out.push("the user agent has no Chrome version");
196
+ if (!o.uaData)
197
+ out.push("navigator.userAgentData is missing");
198
+ else {
199
+ if (major && !o.uaData.brands.some((b) => /^(Google Chrome|Chromium)$/.test(b.brand) && b.version === major))
200
+ out.push(`the client hints brands (${o.uaData.brands.map((b) => `${b.brand} ${b.version}`).join(", ")}) do not name Chrome ${major}`);
201
+ const os = PLATFORMS.find((p) => p.ua.test(o.userAgent));
202
+ if (os && o.uaData.platform !== os.hints)
203
+ out.push(`the user agent is ${os.hints} but the client hints platform is ${o.uaData.platform}`);
204
+ if (os && !os.navigator.test(o.platform))
205
+ out.push(`the user agent is ${os.hints} but navigator.platform is ${o.platform}`);
206
+ if (o.uaData.mobile)
207
+ out.push("the client hints say mobile");
208
+ const high = o.uaData.high;
209
+ // Chrome on Linux reports an empty platform version, as a person's Chrome there does.
210
+ const versionless = o.uaData.platform === "Linux";
211
+ if (high && (!high.fullVersionList.length || !high.architecture || (!high.platformVersion && !versionless)))
212
+ out.push("the client hints high entropy values (full version list, architecture, platform version) are blank");
213
+ else if (high && expected.high && highEntropyKey(high) !== highEntropyKey(expected.high))
214
+ out.push(`the client hints high entropy values (${high.architecture || "no architecture"}, platform version ${high.platformVersion || "empty"}) differ from this Chrome's own (${expected.high.architecture}, platform version ${expected.high.platformVersion || "empty"})`);
215
+ else if (high &&
216
+ major &&
217
+ !high.fullVersionList.some((b) => /^(Google Chrome|Chromium)$/.test(b.brand) && majorOf(b.version) === Number(major)))
218
+ out.push(`the client hints full version list does not name Chrome ${major}`);
219
+ }
220
+ if (expected.languages?.length) {
221
+ if (JSON.stringify(o.languages) !== JSON.stringify(expected.languages))
222
+ out.push(`navigator.languages is ${o.languages.join(", ")}, not ${expected.languages.join(", ")}`);
223
+ }
224
+ const first = expected.languages?.[0] ?? o.languages[0];
225
+ if (first && base(o.intlLocale) !== base(first))
226
+ out.push(`dates and numbers are formatted in ${o.intlLocale}, but the first language is ${first}` +
227
+ (process.platform === "darwin"
228
+ ? " (on macOS Chrome takes that from the system language, not from flags: set languages to start with it, or change the macOS language)"
229
+ : ""));
230
+ if (expected.timezone && o.timezone !== expected.timezone)
231
+ out.push(`the time zone is ${o.timezone}, not ${expected.timezone}`);
232
+ return out;
233
+ }
234
+ /** Runs in a page: what `coherenceProblems` checks. */
235
+ export const OBSERVE_SCRIPT = `async () => {
236
+ const d = navigator.userAgentData;
237
+ const high = d ? await d.getHighEntropyValues(["fullVersionList", "architecture", "platformVersion"]) : null;
238
+ return {
239
+ userAgent: navigator.userAgent,
240
+ platform: navigator.platform,
241
+ languages: Array.from(navigator.languages || []),
242
+ timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
243
+ intlLocale: Intl.DateTimeFormat().resolvedOptions().locale,
244
+ uaData: d
245
+ ? {
246
+ brands: d.brands.map((b) => ({ brand: b.brand, version: b.version })),
247
+ platform: d.platform,
248
+ mobile: d.mobile,
249
+ high: {
250
+ fullVersionList: (high.fullVersionList || []).map((b) => ({ brand: b.brand, version: b.version })),
251
+ architecture: high.architecture || "",
252
+ platformVersion: high.platformVersion || "",
253
+ },
254
+ }
255
+ : null,
256
+ };
257
+ }`;
258
+ /** The installed Chrome's major version from a version string like "157.0.8103.79". */
259
+ export function majorOf(version) {
260
+ const m = /^(\d+)\./.exec(version ?? "");
261
+ return m ? Number(m[1]) : undefined;
262
+ }
263
+ //# sourceMappingURL=network.js.map
@@ -0,0 +1,69 @@
1
+ /**
2
+ * The format 8 keys of identity.json: natural language actions (`act`) and captcha solving
3
+ * (`captcha`). Both are off until the key is there, and both send page content to a third
4
+ * party the user picks, so neither has a default provider:
5
+ *
6
+ * "act": {
7
+ * "sampling": true, // ask the agent's own client (MCP sampling) first
8
+ * "provider": "chat-completions", // else this HTTP API
9
+ * "endpoint": "https://models.example.com/v1",
10
+ * "model": "example-model",
11
+ * "key": "keychain:act-model", // optional; a reference, never the key
12
+ * "maxSteps": 10, "maxTokens": 50000, "timeout": "2m"
13
+ * },
14
+ * "captcha": {
15
+ * "provider": "task-api",
16
+ * "endpoint": "https://solver.example.com",
17
+ * "key": "keychain:captcha-solver",
18
+ * "timeout": "3m"
19
+ * }
20
+ *
21
+ * A key is read from the secret store at use time (turno-core), never from a tool argument and
22
+ * never written here: a value that is not a `keychain:` reference is refused, and the message
23
+ * does not repeat it.
24
+ */
25
+ /** The model providers `act` can name besides MCP sampling. */
26
+ declare const ACT_PROVIDERS: readonly ["chat-completions"];
27
+ /** The captcha solver protocols `captcha` can name. */
28
+ declare const CAPTCHA_PROVIDERS: readonly ["task-api"];
29
+ export interface ActSettings {
30
+ /** Use MCP sampling when the client offers it (default true). */
31
+ sampling?: boolean;
32
+ provider?: (typeof ACT_PROVIDERS)[number];
33
+ /** Base URL of the provider's API: https, or http on a loopback address. */
34
+ endpoint?: string;
35
+ model?: string;
36
+ /** `keychain:<item>`: the API key, read from the secret store. */
37
+ key?: string;
38
+ /** Most actions one `browser_act` call takes (default 10, at most 30). */
39
+ maxSteps?: number;
40
+ /** Most model tokens one call spends, prompts and replies together (default 50000). */
41
+ maxTokens?: number;
42
+ /** Longest one call runs, like `"2m"` (default 2m, from 10s to 10m). */
43
+ timeout?: string;
44
+ }
45
+ export interface CaptchaSettings {
46
+ provider: (typeof CAPTCHA_PROVIDERS)[number];
47
+ endpoint: string;
48
+ /** `keychain:<item>`: the solver's account key, read from the secret store. */
49
+ key: string;
50
+ /** Longest one solve waits, like `"3m"` (default 3m, from 10s to 10m). */
51
+ timeout?: string;
52
+ }
53
+ /** Budgets of one natural language call, after the defaults. */
54
+ export interface ActBudget {
55
+ maxSteps: number;
56
+ maxTokens: number;
57
+ timeoutMs: number;
58
+ }
59
+ /** True for https, or http on a loopback host (a model server on this machine). */
60
+ export declare function allowedEndpoint(value: string): boolean;
61
+ /** Problems with `act`, in key order. */
62
+ export declare function actProblems(a: unknown, out: string[]): void;
63
+ /** Problems with `captcha`, alone and with the engine keys. */
64
+ export declare function captchaProblems(c: unknown, settings: Record<string, unknown>, out: string[]): void;
65
+ /** The budgets of an `act` group, defaults filled in. */
66
+ export declare function actBudget(a: ActSettings): ActBudget;
67
+ /** How long one captcha solve may wait. */
68
+ export declare function captchaTimeoutMs(c: CaptchaSettings): number;
69
+ export {};