turno-browser 0.7.0 → 0.8.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 (47) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/README.md +5 -1
  3. package/dist/act.js +4 -29
  4. package/dist/agent-cursor-overlay.d.ts +10 -0
  5. package/dist/agent-cursor-overlay.js +50 -5
  6. package/dist/agent-cursor.d.ts +39 -7
  7. package/dist/agent-cursor.js +106 -20
  8. package/dist/cli/flows.js +3 -0
  9. package/dist/cli/identity.js +3 -4
  10. package/dist/cli/init.js +4 -2
  11. package/dist/engine-camoufox.js +1 -0
  12. package/dist/engine-lightpanda.js +1 -0
  13. package/dist/host.d.ts +7 -0
  14. package/dist/host.js +313 -76
  15. package/dist/human-step-overlay.d.ts +73 -0
  16. package/dist/human-step-overlay.js +285 -0
  17. package/dist/human-step.d.ts +128 -0
  18. package/dist/human-step.js +521 -0
  19. package/dist/index.d.ts +1 -1
  20. package/dist/index.js +1 -1
  21. package/dist/live-server.d.ts +7 -3
  22. package/dist/live-server.js +13 -15
  23. package/dist/live.d.ts +20 -1
  24. package/dist/live.js +52 -10
  25. package/dist/network-redact.d.ts +28 -0
  26. package/dist/network-redact.js +202 -0
  27. package/dist/recorder.d.ts +0 -21
  28. package/dist/recorder.js +1 -41
  29. package/dist/recordings.d.ts +5 -0
  30. package/dist/recordings.js +4 -2
  31. package/dist/redact.d.ts +7 -0
  32. package/dist/redact.js +32 -1
  33. package/dist/replay.d.ts +2 -0
  34. package/dist/replay.js +33 -14
  35. package/dist/reputation.d.ts +5 -0
  36. package/dist/reputation.js +12 -7
  37. package/dist/sensitive.d.ts +79 -0
  38. package/dist/sensitive.js +275 -0
  39. package/dist/session.d.ts +12 -0
  40. package/dist/session.js +24 -0
  41. package/dist/tools.d.ts +5 -0
  42. package/dist/tools.js +9 -1
  43. package/dist/upstream.d.ts +5 -0
  44. package/dist/watch.d.ts +60 -0
  45. package/dist/watch.js +114 -0
  46. package/npm-shrinkwrap.json +2 -2
  47. package/package.json +1 -1
package/dist/live.d.ts CHANGED
@@ -62,6 +62,8 @@ export type GateOutcome = {
62
62
  kind: "resumed";
63
63
  pausedMs: number;
64
64
  by: string;
65
+ /** The pause was a step an agent asked the person to do (`browser_request_human`). */
66
+ step: boolean;
65
67
  /** The tabs when the pause started (empty when no browser ran). */
66
68
  before: TabState[];
67
69
  /** Clicks, keys and scrolls the user sent through the live view during the pause. */
@@ -70,23 +72,36 @@ export type GateOutcome = {
70
72
  kind: "timeout";
71
73
  pausedMs: number;
72
74
  by: string;
75
+ step: boolean;
73
76
  } | {
74
77
  kind: "aborted";
75
78
  };
79
+ /** How a pause holds calls beyond the live wait: a step the agent asked the person to do. */
80
+ export interface PauseHold {
81
+ /** The pause is a person step (`browser_request_human`), not the user's own pause. */
82
+ step?: boolean;
83
+ /** When the step ends at the latest (epoch ms): a held call waits at least until then. */
84
+ until?: number;
85
+ }
76
86
  /** Holds calls while the user has the browser. One per server: a pause holds every session. */
77
87
  export declare class PauseGate {
78
88
  private readonly now;
79
89
  private pause;
90
+ /** The pause that ended last, for a step the person resumed before it read its input count. */
91
+ private ended;
80
92
  private waiting;
81
93
  constructor(now?: () => number);
82
94
  get paused(): {
83
95
  since: number;
84
96
  by: string;
97
+ step: boolean;
85
98
  } | undefined;
99
+ /** The live view input of the pause that started at `since`, on now or ended last (else 0). */
100
+ inputsOf(since: number | undefined): number;
86
101
  /** Calls waiting for the user now. */
87
102
  get held(): number;
88
103
  /** Starts a pause; false when one is already on. `before` is the tabs as the agent left them. */
89
- start(by: string, before?: Promise<TabState[]>): boolean;
104
+ start(by: string, before?: Promise<TabState[]>, hold?: PauseHold): boolean;
90
105
  /** Ends the pause and lets every held call go; false when there was none. */
91
106
  resume(): boolean;
92
107
  /** The user clicked, typed or scrolled through the live view. */
@@ -111,10 +126,14 @@ export declare function resumeNote(o: {
111
126
  lines: readonly string[];
112
127
  tool: string;
113
128
  ran: boolean;
129
+ /** The pause was a person step another call asked for (`browser_request_human`). */
130
+ step?: boolean;
114
131
  /** A flow is being recorded: what the user did is not in it. */
115
132
  recordingFlow?: boolean;
116
133
  /** The browser is not running, so there is no snapshot. */
117
134
  noBrowser?: boolean;
118
135
  }): string;
136
+ /** The note of a call that was running when a pause started. */
137
+ export declare function pausedWhileRunningNote(step: boolean): string;
119
138
  /** The error of a call whose wait ran out. */
120
139
  export declare function timeoutMessage(identity: string, tool: string, pausedMs: number, by: string, waitMs: number): string;
package/dist/live.js CHANGED
@@ -52,23 +52,35 @@ export function viewRefusal(engine) {
52
52
  return "The view is a Chrome DevTools Protocol screencast, and Camoufox is a Firefox build that has none, so there is nothing to show; Camoufox's own window shows the page when it runs headed. Pause and resume still work.";
53
53
  return undefined;
54
54
  }
55
+ /** How long a held call waits past the end of a person step, for the step to clean up. */
56
+ const STEP_SLACK_MS = 10_000;
55
57
  /** Holds calls while the user has the browser. One per server: a pause holds every session. */
56
58
  export class PauseGate {
57
59
  now;
58
60
  pause;
61
+ /** The pause that ended last, for a step the person resumed before it read its input count. */
62
+ ended;
59
63
  waiting = 0;
60
64
  constructor(now = Date.now) {
61
65
  this.now = now;
62
66
  }
63
67
  get paused() {
64
- return this.pause && { since: this.pause.since, by: this.pause.by };
68
+ return this.pause && { since: this.pause.since, by: this.pause.by, step: this.pause.step };
69
+ }
70
+ /** The live view input of the pause that started at `since`, on now or ended last (else 0). */
71
+ inputsOf(since) {
72
+ if (since === undefined)
73
+ return 0;
74
+ if (this.pause?.since === since)
75
+ return this.pause.inputs;
76
+ return this.ended?.since === since ? this.ended.inputs : 0;
65
77
  }
66
78
  /** Calls waiting for the user now. */
67
79
  get held() {
68
80
  return this.waiting;
69
81
  }
70
82
  /** Starts a pause; false when one is already on. `before` is the tabs as the agent left them. */
71
- start(by, before = Promise.resolve([])) {
83
+ start(by, before = Promise.resolve([]), hold = {}) {
72
84
  if (this.pause)
73
85
  return false;
74
86
  let release;
@@ -76,7 +88,16 @@ export class PauseGate {
76
88
  release = r;
77
89
  });
78
90
  before.catch(() => { });
79
- this.pause = { since: this.now(), by, before, inputs: 0, done, release };
91
+ this.pause = {
92
+ since: this.now(),
93
+ by,
94
+ step: hold.step === true,
95
+ until: hold.until,
96
+ before,
97
+ inputs: 0,
98
+ done,
99
+ release,
100
+ };
80
101
  return true;
81
102
  }
82
103
  /** Ends the pause and lets every held call go; false when there was none. */
@@ -85,6 +106,7 @@ export class PauseGate {
85
106
  if (!p)
86
107
  return false;
87
108
  this.pause = undefined;
109
+ this.ended = { since: p.since, inputs: p.inputs };
88
110
  p.release();
89
111
  return true;
90
112
  }
@@ -101,6 +123,8 @@ export class PauseGate {
101
123
  if (signal?.aborted)
102
124
  return { kind: "aborted" };
103
125
  this.waiting++;
126
+ // A person step holds every call until it ends, however long the live wait is.
127
+ const holdMs = p.until === undefined ? waitMs : Math.max(waitMs, p.until - this.now() + STEP_SLACK_MS);
104
128
  let timer;
105
129
  let onAbort;
106
130
  try {
@@ -108,7 +132,7 @@ export class PauseGate {
108
132
  p.done.then(() => "resumed"),
109
133
  new Promise((r) => {
110
134
  // Each call waits the whole time: a call that arrives late in a pause is held as long.
111
- timer = setTimeout(() => r("timeout"), waitMs);
135
+ timer = setTimeout(() => r("timeout"), holdMs);
112
136
  }),
113
137
  new Promise((r) => {
114
138
  onAbort = () => r("aborted");
@@ -119,8 +143,15 @@ export class PauseGate {
119
143
  return { kind: "aborted" };
120
144
  const pausedMs = this.now() - p.since;
121
145
  if (outcome === "timeout")
122
- return { kind: "timeout", pausedMs, by: p.by };
123
- return { kind: "resumed", pausedMs, by: p.by, before: await p.before.catch(() => []), inputs: p.inputs };
146
+ return { kind: "timeout", pausedMs, by: p.by, step: p.step };
147
+ return {
148
+ kind: "resumed",
149
+ pausedMs,
150
+ by: p.by,
151
+ step: p.step,
152
+ before: await p.before.catch(() => []),
153
+ inputs: p.inputs,
154
+ };
124
155
  }
125
156
  finally {
126
157
  this.waiting--;
@@ -177,10 +208,15 @@ export function describeChanges(before, after, currentBefore, currentAfter, inpu
177
208
  }
178
209
  /** The section a held call's result starts with. */
179
210
  export function resumeNote(o) {
180
- const out = [
181
- "### Paused by the user",
182
- `The user paused this browser (${o.by}) for ${formatPause(o.pausedMs)} and has resumed it.`,
183
- ];
211
+ const out = o.step
212
+ ? [
213
+ "### Waited for the person",
214
+ `A call asked the person to do a step in this browser (${o.by}); it took ${formatPause(o.pausedMs)} and has ended.`,
215
+ ]
216
+ : [
217
+ "### Paused by the user",
218
+ `The user paused this browser (${o.by}) for ${formatPause(o.pausedMs)} and has resumed it.`,
219
+ ];
184
220
  if (o.lines.length)
185
221
  out.push("While you waited:", ...o.lines.map((l) => `- ${l}`));
186
222
  else
@@ -195,6 +231,12 @@ export function resumeNote(o) {
195
231
  out.push("The flow you are recording does not have what the user did.");
196
232
  return out.join("\n");
197
233
  }
234
+ /** The note of a call that was running when a pause started. */
235
+ export function pausedWhileRunningNote(step) {
236
+ return step
237
+ ? "### Waited for the person\nA call asked the person to do a step in this browser while this call ran. Your next call waits until the step ends."
238
+ : "### Paused by the user\nThe user paused this browser while this call ran. Your next call waits until they resume.";
239
+ }
198
240
  /** The error of a call whose wait ran out. */
199
241
  export function timeoutMessage(identity, tool, pausedMs, by, waitMs) {
200
242
  return (`The user paused browser identity "${identity}" ${formatPause(pausedMs)} ago (${by}) and has not resumed it ` +
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Credentials in what `browser_network_requests` and `browser_network_request` show: header
3
+ * values, query parameters, form fields and JSON fields that carry a credential keep their
4
+ * names and lose their values, which read `[redacted]`.
5
+ *
6
+ * - Headers: `Authorization` and `Proxy-Authorization` (the scheme stays: `Bearer [redacted]`),
7
+ * `Cookie` and `Set-Cookie` (each cookie's name stays, its attributes too), and any header
8
+ * named like a credential (`X-Api-Key`, `X-Auth-Token`, `X-CSRF-Token`).
9
+ * - Query parameters, fragment parameters and form fields (`name=value`), and JSON fields
10
+ * (`"name": value`), whose name reads like a credential: `access_token`, `id_token`,
11
+ * `refresh_token`, `token`, `code`, `session`, `sid`, `api_key`, `key`, `secret`, `password`,
12
+ * `client_secret`, `code_verifier`, `signature` and names built on them (`sessionId`,
13
+ * `X-Amz-Security-Token`, `user[password]`).
14
+ *
15
+ * The rest of a request (URL path, other headers, other fields, status) is left as it is, so the
16
+ * agent can still debug the page. A credential in some other shape (a path segment, a custom
17
+ * body format) is not recognized.
18
+ */
19
+ export declare const REDACTED = "[redacted]";
20
+ /** The upstream tools whose output these rules apply to. */
21
+ export declare const NETWORK_TOOLS: ReadonlySet<string>;
22
+ /** True when a header, parameter or field name reads like a credential. */
23
+ export declare function credentialName(name: string): boolean;
24
+ /**
25
+ * The output of the network tools with credentials replaced: a JSON document (a JSON body, a
26
+ * result in JSON mode) field by field and kept in its layout, anything else as text.
27
+ */
28
+ export declare function redactNetworkText(text: string): string;
@@ -0,0 +1,202 @@
1
+ import { wordsOf } from "./sensitive.js";
2
+ /**
3
+ * Credentials in what `browser_network_requests` and `browser_network_request` show: header
4
+ * values, query parameters, form fields and JSON fields that carry a credential keep their
5
+ * names and lose their values, which read `[redacted]`.
6
+ *
7
+ * - Headers: `Authorization` and `Proxy-Authorization` (the scheme stays: `Bearer [redacted]`),
8
+ * `Cookie` and `Set-Cookie` (each cookie's name stays, its attributes too), and any header
9
+ * named like a credential (`X-Api-Key`, `X-Auth-Token`, `X-CSRF-Token`).
10
+ * - Query parameters, fragment parameters and form fields (`name=value`), and JSON fields
11
+ * (`"name": value`), whose name reads like a credential: `access_token`, `id_token`,
12
+ * `refresh_token`, `token`, `code`, `session`, `sid`, `api_key`, `key`, `secret`, `password`,
13
+ * `client_secret`, `code_verifier`, `signature` and names built on them (`sessionId`,
14
+ * `X-Amz-Security-Token`, `user[password]`).
15
+ *
16
+ * The rest of a request (URL path, other headers, other fields, status) is left as it is, so the
17
+ * agent can still debug the page. A credential in some other shape (a path segment, a custom
18
+ * body format) is not recognized.
19
+ */
20
+ export const REDACTED = "[redacted]";
21
+ /** The upstream tools whose output these rules apply to. */
22
+ export const NETWORK_TOOLS = new Set(["browser_network_requests", "browser_network_request"]);
23
+ /** Whole names that carry a credential. */
24
+ const EXACT = new Set([
25
+ "auth",
26
+ "authorization",
27
+ "code",
28
+ "cookie",
29
+ "key",
30
+ "password",
31
+ "secret",
32
+ "session",
33
+ "sid",
34
+ "sig",
35
+ "signature",
36
+ "ticket",
37
+ "token",
38
+ "assertion",
39
+ "samlresponse",
40
+ "jwt",
41
+ "otp",
42
+ ]);
43
+ /** A word anywhere in the name. */
44
+ const WORD = /token|secret|passw(or)?d|passcode|passphrase|sess(ion)?id|^session$|^sid$|^jwt$|apikey|^otp$|credential|verifier|^pwd$|^signature$|cookie/;
45
+ /** `<word>_key` and `<word>_code` names that carry a credential (`api_key`, `auth_code`). */
46
+ const KEY_OWNERS = new Set([
47
+ "api",
48
+ "access",
49
+ "private",
50
+ "secret",
51
+ "client",
52
+ "subscription",
53
+ "auth",
54
+ "session",
55
+ "signing",
56
+ ]);
57
+ const CODE_OWNERS = new Set([
58
+ "auth",
59
+ "authorization",
60
+ "verification",
61
+ "otp",
62
+ "mfa",
63
+ "totp",
64
+ "sms",
65
+ "login",
66
+ "access",
67
+ "device",
68
+ "user",
69
+ "security",
70
+ "time",
71
+ "recovery",
72
+ "backup",
73
+ "confirmation",
74
+ "reset",
75
+ ]);
76
+ /** Names about a credential that do not hold one (`token_endpoint`, `token_type`, `expires_in`). */
77
+ const ABOUT = new Set(["endpoint", "uri", "url", "type", "expires", "expiry", "expiration", "name"]);
78
+ /** Headers whose value is a credential, whatever words they are made of. */
79
+ const HEADERS = new Set(["authorization", "proxy-authorization", "cookie", "set-cookie"]);
80
+ /** True when a header, parameter or field name reads like a credential. */
81
+ export function credentialName(name) {
82
+ const words = wordsOf(name);
83
+ if (!words.length)
84
+ return false;
85
+ if (EXACT.has(words.join("")))
86
+ return true;
87
+ const last = words[words.length - 1];
88
+ if (ABOUT.has(last))
89
+ return false;
90
+ if (words.some((w) => WORD.test(w)))
91
+ return true;
92
+ const before = words[words.length - 2];
93
+ if (before && last === "key" && KEY_OWNERS.has(before))
94
+ return true;
95
+ if (before && last === "code" && CODE_OWNERS.has(before))
96
+ return true;
97
+ return false;
98
+ }
99
+ function decodeName(name) {
100
+ try {
101
+ return decodeURIComponent(name.replace(/\+/g, " "));
102
+ }
103
+ catch {
104
+ return name;
105
+ }
106
+ }
107
+ /** `a=1; b=2` with each value replaced. */
108
+ function redactCookies(value) {
109
+ return value
110
+ .split(";")
111
+ .map((part) => {
112
+ const eq = part.indexOf("=");
113
+ return eq < 0 ? part : `${part.slice(0, eq)}=${REDACTED}`;
114
+ })
115
+ .join(";");
116
+ }
117
+ /** `sid=abc; Path=/; HttpOnly` with the cookie's value replaced and its attributes kept. */
118
+ function redactSetCookie(value) {
119
+ const semi = value.indexOf(";");
120
+ const pair = semi < 0 ? value : value.slice(0, semi);
121
+ const eq = pair.indexOf("=");
122
+ const redacted = eq < 0 ? REDACTED : `${pair.slice(0, eq)}=${REDACTED}`;
123
+ return semi < 0 ? redacted : redacted + value.slice(semi);
124
+ }
125
+ function redactHeaderValue(name, value) {
126
+ const lower = name.toLowerCase();
127
+ if (lower === "authorization" || lower === "proxy-authorization") {
128
+ const m = /^([A-Za-z][\w-]*) +\S/.exec(value);
129
+ return m ? `${m[1]} ${REDACTED}` : REDACTED;
130
+ }
131
+ if (lower === "cookie")
132
+ return redactCookies(value);
133
+ if (lower === "set-cookie")
134
+ return redactSetCookie(value);
135
+ return REDACTED;
136
+ }
137
+ const HEADER_LINE = /^([ \t]*)([!#$%&'*+.^_`|~0-9A-Za-z-]+): (.*)$/;
138
+ const JSON_FIELD = /"((?:[^"\\\n]|\\.){1,100})"(\s*:\s*)("(?:[^"\\\n]|\\.)*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)/g;
139
+ const PAIR = /(^|[?&#;\s])([^\s=&#?;"'<>]{1,100})=([^\s&#;"'<>]*)/g;
140
+ /** Header lines, then JSON fields, then `name=value` pairs, in plain text. */
141
+ function redactPlain(text) {
142
+ let setCookie = false;
143
+ const lines = text.split("\n").map((line) => {
144
+ const m = HEADER_LINE.exec(line);
145
+ if (!m) {
146
+ // Playwright joins several Set-Cookie values with a newline: the next ones have no name.
147
+ if (setCookie && line.trim() && !line.startsWith("#"))
148
+ return redactSetCookie(line);
149
+ setCookie = false;
150
+ return line;
151
+ }
152
+ const [, indent, name, value] = m;
153
+ setCookie = name.toLowerCase() === "set-cookie";
154
+ if (!HEADERS.has(name.toLowerCase()) && !credentialName(name))
155
+ return line;
156
+ return `${indent}${name}: ${redactHeaderValue(name, value)}`;
157
+ });
158
+ return lines
159
+ .join("\n")
160
+ .replace(JSON_FIELD, (all, name, colon) => credentialName(name) ? `"${name}"${colon}"${REDACTED}"` : all)
161
+ .replace(PAIR, (all, lead, name, value) => value && value !== REDACTED && credentialName(decodeName(name)) ? `${lead}${name}=${REDACTED}` : all);
162
+ }
163
+ /** A parsed JSON value with credential fields replaced, and every string redacted as text. */
164
+ function redactJson(value) {
165
+ if (typeof value === "string")
166
+ return redactNetworkText(value);
167
+ if (Array.isArray(value))
168
+ return value.map(redactJson);
169
+ if (!value || typeof value !== "object")
170
+ return value;
171
+ const out = {};
172
+ for (const [k, v] of Object.entries(value)) {
173
+ out[k] =
174
+ credentialName(k) && (typeof v === "string" || typeof v === "number") && v !== REDACTED
175
+ ? REDACTED
176
+ : redactJson(v);
177
+ }
178
+ return out;
179
+ }
180
+ /**
181
+ * The output of the network tools with credentials replaced: a JSON document (a JSON body, a
182
+ * result in JSON mode) field by field and kept in its layout, anything else as text.
183
+ */
184
+ export function redactNetworkText(text) {
185
+ const trimmed = text.trim();
186
+ if ((trimmed.startsWith("{") && trimmed.endsWith("}")) || (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
187
+ try {
188
+ const parsed = JSON.parse(trimmed);
189
+ const redacted = redactJson(parsed);
190
+ const before = JSON.stringify(parsed);
191
+ const after = JSON.stringify(redacted);
192
+ if (before === after)
193
+ return text;
194
+ return trimmed.includes("\n") ? JSON.stringify(redacted, null, 2) : after;
195
+ }
196
+ catch {
197
+ /* not JSON after all: read it as text */
198
+ }
199
+ }
200
+ return redactPlain(text);
201
+ }
202
+ //# sourceMappingURL=network-redact.js.map
@@ -3,26 +3,6 @@ import type { IdentityRef } from "./engine.js";
3
3
  import { type Flow, type FlowStep } from "./flows.js";
4
4
  import type { Redactor } from "./redact.js";
5
5
  import type { TurnoTool } from "./tools.js";
6
- /** What the page says about an element, for its locators and to tell a secret field. */
7
- interface ElementInfo {
8
- tag: string;
9
- type: string;
10
- autocomplete: string;
11
- name: string;
12
- id: string;
13
- text: string;
14
- css: string;
15
- }
16
- export declare const SECRET_AUTOCOMPLETE: RegExp;
17
- export declare const SECRET_NAME: RegExp;
18
- /** A field whose typed value must never be stored. */
19
- export declare function secretField(info: Pick<ElementInfo, "type" | "autocomplete" | "name" | "id">): boolean;
20
- /**
21
- * The values a `browser_type` or `browser_fill_form` call is about to put into secret fields
22
- * (`secretField`), so a recording can stop its trace first. A target the page cannot resolve
23
- * counts as not secret: the call then fails the same way.
24
- */
25
- export declare function secretValues(page: Page, tool: string, args: Record<string, unknown>): Promise<string[]>;
26
6
  /**
27
7
  * Role and accessible name from Playwright's generated locator when it is a role locator
28
8
  * (`internal:role=button[name="Sign in"i]`). Asking the element for its aria snapshot instead
@@ -85,4 +65,3 @@ export declare class FlowRecorder {
85
65
  }
86
66
  /** `browser_record`. */
87
67
  export declare function recordTool(): TurnoTool;
88
- export {};
package/dist/recorder.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { AUTO_PREFIX, FlowError, FLOW_FORMAT_VERSION, MAX_FLOW_STEPS, assertFlowName, describeStep, flowPath, getPath, rotateAutoFlows, setPath, writeFlow, } from "./flows.js";
2
2
  import { existsSync } from "node:fs";
3
+ import { secretField } from "./sensitive.js";
3
4
  import { upstream } from "./upstream.js";
4
5
  /**
5
6
  * Flow recording. While a session records (the agent called `browser_record`, or the
@@ -47,47 +48,6 @@ function recordsTool(name, args) {
47
48
  // Listing tabs changes nothing.
48
49
  return !(name === "browser_tabs" && (args.action ?? "list") === "list");
49
50
  }
50
- export const SECRET_AUTOCOMPLETE = /(^|\s)(current-password|new-password|one-time-code|cc-number|cc-csc|cc-exp(-month|-year)?)(\s|$)/i;
51
- export const SECRET_NAME = /pass(word|wd|code)?|pwd|otp|totp|2fa|mfa|(^|[^a-z])pin([^a-z]|$)|cvv|cvc|csc|secret|token|ssn/i;
52
- /** A field whose typed value must never be stored. */
53
- export function secretField(info) {
54
- if (info.type === "password")
55
- return true;
56
- if (SECRET_AUTOCOMPLETE.test(info.autocomplete))
57
- return true;
58
- return SECRET_NAME.test(`${info.name} ${info.id}`);
59
- }
60
- /**
61
- * The values a `browser_type` or `browser_fill_form` call is about to put into secret fields
62
- * (`secretField`), so a recording can stop its trace first. A target the page cannot resolve
63
- * counts as not secret: the call then fails the same way.
64
- */
65
- export async function secretValues(page, tool, args) {
66
- const pairs = tool === "browser_type"
67
- ? [[args.target, args.text]]
68
- : tool === "browser_fill_form" && Array.isArray(args.fields)
69
- ? args.fields
70
- .filter((f) => f.type === "textbox")
71
- .map((f) => [f.target, f.value])
72
- : [];
73
- const out = [];
74
- for (const [target, value] of pairs) {
75
- if (typeof target !== "string" || typeof value !== "string" || !value)
76
- continue;
77
- const locator = page.locator(REF.test(target) ? `aria-ref=${target}` : target);
78
- const info = await locator
79
- .evaluate((el) => ({
80
- type: (el.type || "").toLowerCase(),
81
- autocomplete: el.getAttribute("autocomplete") ?? "",
82
- name: el.getAttribute("name") ?? "",
83
- id: el.id,
84
- }), undefined, { timeout: 2_000 })
85
- .catch(() => undefined);
86
- if (info && secretField(info))
87
- out.push(value);
88
- }
89
- return out;
90
- }
91
51
  /** Playwright's attribute value syntax: `"Sign in"s` (exact) for role and text selectors. */
92
52
  function quoteExact(text) {
93
53
  return `"${text.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"s`;
@@ -58,6 +58,11 @@ export interface RecordingOptions {
58
58
  idleMs?: number;
59
59
  /** Why traces cannot be recorded in this session (another trace owner); screenshots still are. */
60
60
  noTraces?: string;
61
+ /**
62
+ * Runs before a trace is saved: the host reads the sensitive fields of every page, so a value
63
+ * the person typed since the last tool call joins the redactor and the search below finds it.
64
+ */
65
+ beforeSave?: () => Promise<void>;
61
66
  now?: () => Date;
62
67
  }
63
68
  /** The recording of one browser session (one launch). */
@@ -21,8 +21,9 @@ import { parseSize } from "./units.js";
21
21
  * - It starts again at the first call after every page that holds those values has navigated
22
22
  * away (the vault guard), so neither the filled form nor the request that sends it is traced.
23
23
  * - Each saved trace is read back and searched for the passwords, one-time codes and sensitive
24
- * values this server knows, in the encodings the redactor knows; a trace that holds one, or
25
- * that cannot be read while such values exist, is deleted.
24
+ * values this server knows (the values of the pages' password and one-time code fields are
25
+ * read just before), in the encodings the redactor knows; a trace that holds one, or that
26
+ * cannot be read while such values exist, is deleted.
26
27
  * - No screenshot is taken of a page while it holds those values. There is no video: a video
27
28
  * cannot leave the sign-in out.
28
29
  *
@@ -326,6 +327,7 @@ export class Recording {
326
327
  const entry = { file: name, from: this.segmentFrom, to: this.index.steps.length };
327
328
  if (entry.to < entry.from)
328
329
  entry.from = entry.to = 0;
330
+ await this.o.beforeSave?.().catch(() => { });
329
331
  try {
330
332
  await this.o.context.tracing.stop({ path: file });
331
333
  }
package/dist/redact.d.ts CHANGED
@@ -4,8 +4,15 @@ import type { ToolResult } from "./upstream.js";
4
4
  export declare function variantsOf(value: string): string[];
5
5
  export declare class Redactor {
6
6
  private readonly entries;
7
+ private readonly fields;
7
8
  /** Redact `value` from now on, shown as `[vault: <label>]`; `ttlMs` for a one-time code. */
8
9
  add(value: string, label: string, ttlMs?: number, now?: number): void;
10
+ /**
11
+ * Redact a value read from a sensitive field of a page, whoever typed it (the person, a page
12
+ * script), shown as `mark`; `ttlMs` for a one-time code. A value the vault already hides
13
+ * keeps its vault label.
14
+ */
15
+ addField(value: string, mark: string, ttlMs?: number, now?: number): void;
9
16
  /** True when there is something to redact. */
10
17
  get active(): boolean;
11
18
  /** True when `text` holds a value this redactor hides, in any of its forms. */
package/dist/redact.js CHANGED
@@ -32,18 +32,48 @@ export function variantsOf(value) {
32
32
  out.add(htmlEscape(value));
33
33
  return [...out].filter((v) => v.length >= MIN_LENGTH);
34
34
  }
35
+ /** Most values read from sensitive fields kept at once; the oldest go first. */
36
+ const MAX_FIELD_VALUES = 256;
35
37
  export class Redactor {
36
38
  entries = new Map();
39
+ fields = new Set();
37
40
  /** Redact `value` from now on, shown as `[vault: <label>]`; `ttlMs` for a one-time code. */
38
41
  add(value, label, ttlMs, now = Date.now()) {
39
42
  if (value.length < MIN_LENGTH)
40
43
  return;
44
+ this.fields.delete(value);
41
45
  this.entries.set(value, {
42
46
  label,
43
47
  variants: variantsOf(value),
44
48
  ...(ttlMs !== undefined ? { until: now + ttlMs } : {}),
45
49
  });
46
50
  }
51
+ /**
52
+ * Redact a value read from a sensitive field of a page, whoever typed it (the person, a page
53
+ * script), shown as `mark`; `ttlMs` for a one-time code. A value the vault already hides
54
+ * keeps its vault label.
55
+ */
56
+ addField(value, mark, ttlMs, now = Date.now()) {
57
+ if (value.length < MIN_LENGTH)
58
+ return;
59
+ const known = this.entries.get(value);
60
+ if (known && !this.fields.has(value))
61
+ return;
62
+ this.fields.delete(value);
63
+ this.fields.add(value);
64
+ this.entries.set(value, {
65
+ label: "sensitive field",
66
+ mark,
67
+ variants: variantsOf(value),
68
+ ...(ttlMs !== undefined ? { until: now + ttlMs } : {}),
69
+ });
70
+ for (const old of this.fields) {
71
+ if (this.fields.size <= MAX_FIELD_VALUES)
72
+ break;
73
+ this.fields.delete(old);
74
+ this.entries.delete(old);
75
+ }
76
+ }
47
77
  /** True when there is something to redact. */
48
78
  get active() {
49
79
  return this.entries.size > 0;
@@ -73,10 +103,11 @@ export class Redactor {
73
103
  for (const [value, e] of this.entries) {
74
104
  if (e.until !== undefined && now > e.until) {
75
105
  this.entries.delete(value);
106
+ this.fields.delete(value);
76
107
  continue;
77
108
  }
78
109
  for (const v of e.variants)
79
- pairs.push([v, `[vault: ${e.label}]`]);
110
+ pairs.push([v, e.mark ?? `[vault: ${e.label}]`]);
80
111
  }
81
112
  // Longest first, so a value inside another value's encoding is handled by the longer one.
82
113
  pairs.sort((a, b) => b[0].length - a[0].length);
package/dist/replay.d.ts CHANGED
@@ -5,6 +5,8 @@ export declare function replayTool(): TurnoTool;
5
5
  export declare function flowsTool(): TurnoTool;
6
6
  export interface ReplayOptions {
7
7
  params?: Record<string, string>;
8
+ /** The sensitive parameters the person typed at a hidden prompt, so they may go into a password field. */
9
+ prompted?: readonly string[];
8
10
  from?: number;
9
11
  headless?: boolean;
10
12
  env?: NodeJS.ProcessEnv;