turno-browser 0.2.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 (121) hide show
  1. package/CHANGELOG.md +228 -0
  2. package/README.md +205 -16
  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 +96 -0
  8. package/dist/api.js +88 -0
  9. package/dist/argv.d.ts +55 -3
  10. package/dist/argv.js +190 -10
  11. package/dist/batch.d.ts +19 -0
  12. package/dist/batch.js +148 -0
  13. package/dist/bench.d.ts +1 -1
  14. package/dist/bench.js +21 -5
  15. package/dist/bin/mcp.js +108 -12
  16. package/dist/captcha.d.ts +77 -0
  17. package/dist/captcha.js +333 -0
  18. package/dist/cdp-relay.d.ts +20 -0
  19. package/dist/cdp-relay.js +101 -0
  20. package/dist/chrome-features.d.ts +23 -0
  21. package/dist/chrome-features.js +44 -0
  22. package/dist/detectors.d.ts +11 -0
  23. package/dist/detectors.js +46 -4
  24. package/dist/diagnose.d.ts +45 -0
  25. package/dist/diagnose.js +326 -0
  26. package/dist/doctor.d.ts +85 -0
  27. package/dist/doctor.js +556 -0
  28. package/dist/engine-attach.d.ts +27 -0
  29. package/dist/engine-attach.js +165 -0
  30. package/dist/engine-camoufox.d.ts +32 -0
  31. package/dist/engine-camoufox.js +270 -0
  32. package/dist/engine-lightpanda.d.ts +72 -0
  33. package/dist/engine-lightpanda.js +292 -0
  34. package/dist/engine.d.ts +119 -0
  35. package/dist/engine.js +355 -0
  36. package/dist/flows.d.ts +127 -0
  37. package/dist/flows.js +294 -0
  38. package/dist/governor.d.ts +119 -0
  39. package/dist/governor.js +325 -0
  40. package/dist/health.d.ts +60 -0
  41. package/dist/health.js +86 -0
  42. package/dist/host.d.ts +95 -0
  43. package/dist/host.js +1181 -0
  44. package/dist/human-input.d.ts +84 -0
  45. package/dist/human-input.js +443 -0
  46. package/dist/humanize.d.ts +123 -0
  47. package/dist/humanize.js +241 -0
  48. package/dist/identities.d.ts +23 -10
  49. package/dist/identities.js +45 -37
  50. package/dist/idle-timer.d.ts +12 -0
  51. package/dist/idle-timer.js +25 -0
  52. package/dist/ids.d.ts +9 -0
  53. package/dist/ids.js +34 -0
  54. package/dist/index.d.ts +21 -6
  55. package/dist/index.js +19 -18
  56. package/dist/lifecycle.d.ts +99 -0
  57. package/dist/lifecycle.js +172 -0
  58. package/dist/live-client.d.ts +22 -0
  59. package/dist/live-client.js +93 -0
  60. package/dist/live-page.d.ts +11 -0
  61. package/dist/live-page.js +143 -0
  62. package/dist/live-server.d.ts +173 -0
  63. package/dist/live-server.js +640 -0
  64. package/dist/live.d.ts +120 -0
  65. package/dist/live.js +203 -0
  66. package/dist/login-tool.d.ts +45 -0
  67. package/dist/login-tool.js +233 -0
  68. package/dist/login.d.ts +8 -3
  69. package/dist/login.js +65 -26
  70. package/dist/network-chrome.d.ts +74 -0
  71. package/dist/network-chrome.js +178 -0
  72. package/dist/network.d.ts +125 -0
  73. package/dist/network.js +263 -0
  74. package/dist/opt-in-settings.d.ts +69 -0
  75. package/dist/opt-in-settings.js +151 -0
  76. package/dist/patchright.d.ts +4 -2
  77. package/dist/patchright.js +4 -2
  78. package/dist/recorder.d.ts +88 -0
  79. package/dist/recorder.js +538 -0
  80. package/dist/recordings.d.ts +116 -0
  81. package/dist/recordings.js +474 -0
  82. package/dist/redact.d.ts +34 -0
  83. package/dist/redact.js +135 -0
  84. package/dist/replay.d.ts +20 -0
  85. package/dist/replay.js +382 -0
  86. package/dist/reputation.d.ts +89 -0
  87. package/dist/reputation.js +203 -0
  88. package/dist/resources.d.ts +76 -0
  89. package/dist/resources.js +341 -0
  90. package/dist/runtime-lock.d.ts +59 -0
  91. package/dist/runtime-lock.js +131 -0
  92. package/dist/sealed.d.ts +8 -0
  93. package/dist/sealed.js +96 -0
  94. package/dist/session-export.d.ts +67 -0
  95. package/dist/session-export.js +194 -0
  96. package/dist/session.d.ts +20 -0
  97. package/dist/session.js +30 -0
  98. package/dist/settings.d.ts +246 -0
  99. package/dist/settings.js +530 -0
  100. package/dist/sharing.d.ts +96 -0
  101. package/dist/sharing.js +269 -0
  102. package/dist/snippet.d.ts +8 -0
  103. package/dist/snippet.js +22 -0
  104. package/dist/tab-locks.d.ts +63 -0
  105. package/dist/tab-locks.js +179 -0
  106. package/dist/tools.d.ts +111 -0
  107. package/dist/tools.js +59 -0
  108. package/dist/totp.d.ts +32 -0
  109. package/dist/totp.js +82 -0
  110. package/dist/tuning.d.ts +76 -0
  111. package/dist/tuning.js +69 -0
  112. package/dist/units.d.ts +8 -0
  113. package/dist/units.js +20 -0
  114. package/dist/upstream.d.ts +243 -0
  115. package/dist/upstream.js +46 -0
  116. package/dist/vault.d.ts +91 -0
  117. package/dist/vault.js +273 -0
  118. package/npm-shrinkwrap.json +1074 -3
  119. package/package.json +5 -4
  120. package/dist/paths.d.ts +0 -17
  121. package/dist/paths.js +0 -17
@@ -0,0 +1,91 @@
1
+ import { type SecretStore } from "turno-core/secrets";
2
+ import { IdentityError } from "./ids.js";
3
+ import { type TotpParams } from "./totp.js";
4
+ /**
5
+ * The credential vault of a browser identity: a username, a password and optionally
6
+ * a TOTP secret per site, so `browser_login` can fill a sign-in form without the model ever
7
+ * seeing them.
8
+ *
9
+ * - The values live only in the OS secret store (turno-core: the macOS Keychain or the Linux
10
+ * Secret Service), one item per site named `turno-browser/vault/<identity>/<site>`, holding one
11
+ * line of JSON. Nothing here writes a value to a file, a log or an error message.
12
+ * - An index next to identity.json (`<data>/browser/identities/<id>.vault.json`, mode 600) lists
13
+ * the sites with their origins and whether they have a TOTP secret, plus the identity's submit
14
+ * policy. It holds no username, password or secret, so `vault list` never reads the store.
15
+ * - A site's origins bind its credentials: `browser_login` fills them only into frames of those
16
+ * origins, never into whatever page the model happens to be on.
17
+ */
18
+ export declare class VaultError extends IdentityError {
19
+ constructor(message: string);
20
+ }
21
+ /** `confirm` (the default): browser_login fills and the model clicks sign in itself. `auto`: it also submits. */
22
+ export type SubmitPolicy = "confirm" | "auto";
23
+ export interface VaultSite {
24
+ site: string;
25
+ /** The origins (scheme, host, port) the credentials may be filled into. */
26
+ origins: string[];
27
+ /** A TOTP secret is stored with the credentials. */
28
+ totp: boolean;
29
+ created: string;
30
+ updated: string;
31
+ }
32
+ /** What the store holds for one site. Never logged, never returned to a model. */
33
+ export interface Credential {
34
+ username: string;
35
+ password: string;
36
+ totp?: TotpParams;
37
+ }
38
+ export interface VaultOptions {
39
+ env?: NodeJS.ProcessEnv;
40
+ /** The secret store (tests pass a fake); default: this machine's. */
41
+ store?: SecretStore;
42
+ now?: Date;
43
+ }
44
+ /**
45
+ * The origin of a sign-in URL, refusing what the vault must never fill into: anything but
46
+ * https, except http on this machine (localhost, 127.0.0.1, [::1]) for local development.
47
+ */
48
+ export declare function vaultOrigin(url: string): string;
49
+ /** The item name of a site's credentials in the secret store. */
50
+ export declare function vaultItem(id: string, site: string): string;
51
+ export declare function vaultPath(id: string, env?: NodeJS.ProcessEnv): string;
52
+ export interface VaultInfo {
53
+ identity: string;
54
+ submit: SubmitPolicy;
55
+ sites: (VaultSite & {
56
+ stored: boolean;
57
+ })[];
58
+ }
59
+ /** The sites of an identity's vault and whether each item is still in the store (values are never read). */
60
+ export declare function vaultList(id: string, options?: VaultOptions): Promise<VaultInfo>;
61
+ export interface VaultAddInput {
62
+ /** The sign-in page, or any URL of each origin the credentials may be filled into. */
63
+ urls: string[];
64
+ username: string;
65
+ password: string;
66
+ /** A base32 TOTP secret or an otpauth://totp/ URI. */
67
+ totp?: string;
68
+ }
69
+ /**
70
+ * Store a site's credentials (replacing what was there) and record it in the index. The item is
71
+ * deleted before it is written again: replacing a Keychain item in place makes macOS ask for
72
+ * keychain access in a dialog, which a server or a script cannot answer.
73
+ */
74
+ export declare function vaultAdd(id: string, site: string, input: VaultAddInput, options?: VaultOptions): Promise<VaultSite>;
75
+ /** Delete a site's credentials and its index entry; false when the vault had neither. */
76
+ export declare function vaultRemove(id: string, site: string, options?: VaultOptions): Promise<boolean>;
77
+ /** Delete every credential of an identity and its index (before the identity itself is removed). */
78
+ export declare function vaultClear(id: string, options?: VaultOptions): Promise<number>;
79
+ /** Choose whether browser_login submits the form itself (`auto`) or leaves that to the model. */
80
+ export declare function vaultSetSubmit(id: string, submit: SubmitPolicy, options?: Pick<VaultOptions, "env">): SubmitPolicy;
81
+ /** One site's entry and the identity's submit policy, for browser_login; undefined when the site is not in the vault. */
82
+ export declare function vaultSite(id: string, site: string, env?: NodeJS.ProcessEnv): {
83
+ site: VaultSite;
84
+ submit: SubmitPolicy;
85
+ } | undefined;
86
+ /** A site's credentials from the store, for browser_login only. Errors never include the item's content. */
87
+ export declare function readCredential(id: string, site: string, options?: VaultOptions): Promise<Credential>;
88
+ /** True when the identity's vault lists any site (an unreadable index counts as yes). */
89
+ export declare function vaultHasSites(id: string, env?: NodeJS.ProcessEnv): boolean;
90
+ /** True when `url` is on one of the site's origins. */
91
+ export declare function originAllowed(site: Pick<VaultSite, "origins">, url: string): boolean;
package/dist/vault.js ADDED
@@ -0,0 +1,273 @@
1
+ import { readFileSync, renameSync, rmSync, statSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { browserPaths, writePrivateFile } from "turno-core/paths";
4
+ import { requireSecretStore } from "turno-core/secrets";
5
+ import { IdentityError, assertIdentityId, identityDir } from "./ids.js";
6
+ import { parseTotpSecret } from "./totp.js";
7
+ /**
8
+ * The credential vault of a browser identity: a username, a password and optionally
9
+ * a TOTP secret per site, so `browser_login` can fill a sign-in form without the model ever
10
+ * seeing them.
11
+ *
12
+ * - The values live only in the OS secret store (turno-core: the macOS Keychain or the Linux
13
+ * Secret Service), one item per site named `turno-browser/vault/<identity>/<site>`, holding one
14
+ * line of JSON. Nothing here writes a value to a file, a log or an error message.
15
+ * - An index next to identity.json (`<data>/browser/identities/<id>.vault.json`, mode 600) lists
16
+ * the sites with their origins and whether they have a TOTP secret, plus the identity's submit
17
+ * policy. It holds no username, password or secret, so `vault list` never reads the store.
18
+ * - A site's origins bind its credentials: `browser_login` fills them only into frames of those
19
+ * origins, never into whatever page the model happens to be on.
20
+ */
21
+ export class VaultError extends IdentityError {
22
+ constructor(message) {
23
+ super(message);
24
+ this.name = "VaultError";
25
+ }
26
+ }
27
+ const SITE = /^[a-z0-9][a-z0-9._-]{0,62}$/;
28
+ const MAX_ORIGINS = 10;
29
+ const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]);
30
+ function assertSiteKey(site) {
31
+ if (!SITE.test(site))
32
+ throw new VaultError(`invalid site key "${site}": use lowercase letters, digits, ".", "-" and "_" (for example "github")`);
33
+ }
34
+ /**
35
+ * The origin of a sign-in URL, refusing what the vault must never fill into: anything but
36
+ * https, except http on this machine (localhost, 127.0.0.1, [::1]) for local development.
37
+ */
38
+ export function vaultOrigin(url) {
39
+ let u;
40
+ try {
41
+ u = new URL(url);
42
+ }
43
+ catch {
44
+ throw new VaultError(`"${url}" is not a URL (for example https://github.com/login)`);
45
+ }
46
+ if (u.protocol === "https:")
47
+ return u.origin;
48
+ if (u.protocol === "http:" && LOOPBACK.has(u.hostname))
49
+ return u.origin;
50
+ throw new VaultError(`${u.origin || url}: the vault fills only https:// pages (http:// only on localhost)`);
51
+ }
52
+ /** The item name of a site's credentials in the secret store. */
53
+ export function vaultItem(id, site) {
54
+ return `turno-browser/vault/${id}/${site}`;
55
+ }
56
+ export function vaultPath(id, env = process.env) {
57
+ assertIdentityId(id);
58
+ return join(browserPaths(env).identitiesDir, `${id}.vault.json`);
59
+ }
60
+ const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
61
+ function isIndex(v) {
62
+ if (!isObject(v) || v.version !== 1 || (v.submit !== "confirm" && v.submit !== "auto") || !isObject(v.sites))
63
+ return false;
64
+ return Object.entries(v.sites).every(([k, s]) => SITE.test(k) &&
65
+ isObject(s) &&
66
+ Array.isArray(s.origins) &&
67
+ s.origins.every((o) => typeof o === "string") &&
68
+ typeof s.totp === "boolean" &&
69
+ typeof s.created === "string" &&
70
+ typeof s.updated === "string");
71
+ }
72
+ function readIndex(id, env) {
73
+ const file = vaultPath(id, env);
74
+ let text;
75
+ try {
76
+ text = readFileSync(file, "utf8");
77
+ }
78
+ catch (err) {
79
+ if (err.code === "ENOENT")
80
+ return { version: 1, submit: "confirm", sites: {} };
81
+ throw err;
82
+ }
83
+ let v;
84
+ try {
85
+ v = JSON.parse(text);
86
+ }
87
+ catch {
88
+ v = undefined;
89
+ }
90
+ if (isObject(v) && typeof v.version === "number" && v.version > 1)
91
+ throw new VaultError(`${file} is from a newer turno-browser; update turno-browser`);
92
+ if (!isIndex(v))
93
+ throw new VaultError(`${file} is not a valid vault index; fix or remove it (the credentials stay in the secret store)`);
94
+ return v;
95
+ }
96
+ function writeIndex(id, index, env) {
97
+ const file = vaultPath(id, env);
98
+ const sites = Object.fromEntries(Object.keys(index.sites)
99
+ .sort()
100
+ .map((k) => [k, index.sites[k]]));
101
+ const tmp = `${file}.${process.pid}.tmp`;
102
+ writePrivateFile(tmp, `${JSON.stringify({ version: 1, submit: index.submit, sites }, null, 2)}\n`, env);
103
+ renameSync(tmp, file);
104
+ }
105
+ function storeOf(options) {
106
+ if (options.store)
107
+ return options.store;
108
+ try {
109
+ return requireSecretStore(options.env ?? process.env);
110
+ }
111
+ catch (err) {
112
+ throw new VaultError(err.message);
113
+ }
114
+ }
115
+ /** Store errors name the item, never the value; this keeps them that way and makes them VaultErrors. */
116
+ async function guarded(what, run) {
117
+ try {
118
+ return await run();
119
+ }
120
+ catch (err) {
121
+ throw new VaultError(`${what}: ${err.message}`);
122
+ }
123
+ }
124
+ /** The sites of an identity's vault and whether each item is still in the store (values are never read). */
125
+ export async function vaultList(id, options = {}) {
126
+ const env = options.env ?? process.env;
127
+ const index = readIndex(id, env);
128
+ const entries = Object.entries(index.sites);
129
+ const store = entries.length ? storeOf(options) : undefined;
130
+ const sites = [];
131
+ for (const [site, s] of entries) {
132
+ const stored = await guarded(`checking ${site}`, () => store.has(vaultItem(id, site)));
133
+ sites.push({ site, ...s, stored });
134
+ }
135
+ return { identity: id, submit: index.submit, sites };
136
+ }
137
+ /**
138
+ * Store a site's credentials (replacing what was there) and record it in the index. The item is
139
+ * deleted before it is written again: replacing a Keychain item in place makes macOS ask for
140
+ * keychain access in a dialog, which a server or a script cannot answer.
141
+ */
142
+ export async function vaultAdd(id, site, input, options = {}) {
143
+ const env = options.env ?? process.env;
144
+ assertIdentityId(id);
145
+ assertSiteKey(site);
146
+ if (!existsDir(identityDir(id, env)))
147
+ throw new VaultError(`identity "${id}" does not exist (turno browser add ${id})`);
148
+ if (!input.urls.length)
149
+ throw new VaultError("give the sign-in page with --url (for example --url https://github.com/login)");
150
+ const origins = [...new Set(input.urls.map(vaultOrigin))];
151
+ if (origins.length > MAX_ORIGINS)
152
+ throw new VaultError(`at most ${MAX_ORIGINS} origins per site`);
153
+ if (!input.username)
154
+ throw new VaultError("the username is empty");
155
+ if (!input.password)
156
+ throw new VaultError("the password is empty");
157
+ if (/[\0\r\n]/.test(input.username))
158
+ throw new VaultError("the username has a line break");
159
+ const totp = input.totp ? parseTotpSecret(input.totp) : undefined;
160
+ const index = readIndex(id, env);
161
+ const store = storeOf(options);
162
+ const item = vaultItem(id, site);
163
+ const credential = { username: input.username, password: input.password, ...(totp ? { totp } : {}) };
164
+ await guarded(`storing ${site}`, async () => {
165
+ await store.remove(item);
166
+ await store.set(item, JSON.stringify({ v: 1, ...credential }));
167
+ });
168
+ const stamp = (options.now ?? new Date()).toISOString();
169
+ const entry = { origins, totp: !!totp, created: index.sites[site]?.created ?? stamp, updated: stamp };
170
+ index.sites[site] = entry;
171
+ writeIndex(id, index, env);
172
+ return { site, ...entry };
173
+ }
174
+ /** Delete a site's credentials and its index entry; false when the vault had neither. */
175
+ export async function vaultRemove(id, site, options = {}) {
176
+ const env = options.env ?? process.env;
177
+ assertSiteKey(site);
178
+ const index = readIndex(id, env);
179
+ const removed = await guarded(`removing ${site}`, () => storeOf(options).remove(vaultItem(id, site)));
180
+ const listed = site in index.sites;
181
+ if (listed) {
182
+ delete index.sites[site];
183
+ writeIndex(id, index, env);
184
+ }
185
+ return removed || listed;
186
+ }
187
+ /** Delete every credential of an identity and its index (before the identity itself is removed). */
188
+ export async function vaultClear(id, options = {}) {
189
+ const env = options.env ?? process.env;
190
+ const index = readIndex(id, env);
191
+ const sites = Object.keys(index.sites);
192
+ if (sites.length) {
193
+ const store = storeOf(options);
194
+ for (const site of sites)
195
+ await guarded(`removing ${site}`, () => store.remove(vaultItem(id, site)));
196
+ }
197
+ rmSync(vaultPath(id, env), { force: true });
198
+ return sites.length;
199
+ }
200
+ /** Choose whether browser_login submits the form itself (`auto`) or leaves that to the model. */
201
+ export function vaultSetSubmit(id, submit, options = {}) {
202
+ const env = options.env ?? process.env;
203
+ if (submit !== "confirm" && submit !== "auto")
204
+ throw new VaultError(`submit must be "confirm" or "auto"`);
205
+ if (!existsDir(identityDir(id, env)))
206
+ throw new VaultError(`identity "${id}" does not exist (turno browser add ${id})`);
207
+ const index = readIndex(id, env);
208
+ index.submit = submit;
209
+ writeIndex(id, index, env);
210
+ return submit;
211
+ }
212
+ /** One site's entry and the identity's submit policy, for browser_login; undefined when the site is not in the vault. */
213
+ export function vaultSite(id, site, env = process.env) {
214
+ assertSiteKey(site);
215
+ const index = readIndex(id, env);
216
+ const s = index.sites[site];
217
+ return s ? { site: { site, ...s }, submit: index.submit } : undefined;
218
+ }
219
+ function isCredential(v) {
220
+ if (!isObject(v) || v.v !== 1 || typeof v.username !== "string" || typeof v.password !== "string")
221
+ return false;
222
+ if (v.totp === undefined)
223
+ return true;
224
+ const t = v.totp;
225
+ return (isObject(t) &&
226
+ typeof t.secret === "string" &&
227
+ typeof t.digits === "number" &&
228
+ typeof t.period === "number" &&
229
+ ["SHA1", "SHA256", "SHA512"].includes(t.algorithm));
230
+ }
231
+ /** A site's credentials from the store, for browser_login only. Errors never include the item's content. */
232
+ export async function readCredential(id, site, options = {}) {
233
+ const raw = await guarded(`reading ${site}`, () => storeOf(options).get(vaultItem(id, site)));
234
+ if (raw === undefined)
235
+ throw new VaultError(`the credentials of "${site}" are missing from the secret store; add them again with turno browser vault add ${id} ${site}`);
236
+ let v;
237
+ try {
238
+ v = JSON.parse(raw);
239
+ }
240
+ catch {
241
+ v = undefined;
242
+ }
243
+ if (!isCredential(v))
244
+ throw new VaultError(`the secret store item of "${site}" is not a turno-browser credential; add it again with turno browser vault add ${id} ${site}`);
245
+ return { username: v.username, password: v.password, ...(v.totp ? { totp: v.totp } : {}) };
246
+ }
247
+ /** True when the identity's vault lists any site (an unreadable index counts as yes). */
248
+ export function vaultHasSites(id, env = process.env) {
249
+ try {
250
+ return Object.keys(readIndex(id, env).sites).length > 0;
251
+ }
252
+ catch {
253
+ return true;
254
+ }
255
+ }
256
+ /** True when `url` is on one of the site's origins. */
257
+ export function originAllowed(site, url) {
258
+ try {
259
+ return site.origins.includes(new URL(url).origin);
260
+ }
261
+ catch {
262
+ return false;
263
+ }
264
+ }
265
+ function existsDir(dir) {
266
+ try {
267
+ return statSync(dir).isDirectory();
268
+ }
269
+ catch {
270
+ return false;
271
+ }
272
+ }
273
+ //# sourceMappingURL=vault.js.map