wb-browser-runtime 0.13.0 → 0.14.1

package/README.md

@@ -122,6 +122,8 @@ Verb arguments support two substitutions at dispatch time:
 
 Both forms are redacted in stdout summaries — only the verb name + selector make it into the log. Expanded values are also scrubbed from `verb.failed` / `slice.failed` error messages before they cross the stdio boundary.
 
+**Escaping.** To emit a literal `{{ … }}` that should *not* be substituted, prefix it with a backslash: `\{{ env.X }}` round-trips to the literal text `{{ env.X }}`. The escape is a single left-to-right pass, so the braces it produces are not re-scanned.
+
 **Missing-value policy.** Set `WB_SUBSTITUTION_ON_MISSING` to choose how a missing `env.X` or `artifacts.X` is handled:
 
 - `warn` (default) — log a stderr warning and substitute an empty string; the verb continues.
@@ -166,10 +168,16 @@ endpoint at session close. Recording is **off by default** — set
 | `WB_RECORDING_SCREENCAST_QUALITY`  | `60`       | JPEG quality (0–100).                             |
 | `WB_RECORDING_RRWEB`               | `1`        | Set `0` to skip rrweb even if recording is on.    |
 | `WB_RECORDING_VIDEO`               | `0` if no `ffmpeg` | Set `0` to skip video even if `ffmpeg` is present. |
+| `WB_RECORDING_MASK_ALL_INPUTS`     | `1`        | rrweb `maskAllInputs`. Set `0` to record input *values* (off by default for safety). |
+| `WB_RECORDING_MASK_TEXT_SELECTOR`  | *(unset)*  | CSS selector whose **text content** rrweb masks (e.g. `.ssn, .acct-balance`). |
+| `WB_RECORDING_BLOCK_SELECTOR`      | *(unset)*  | CSS selector rrweb records as an inert placeholder (contents never captured). |
+| `WB_RECORDING_IGNORE_SELECTOR`     | *(unset)*  | CSS selector for elements to exclude from the recording. **In this build it is applied as a block selector** (unioned with `WB_RECORDING_BLOCK_SELECTOR`): the matching element is recorded as an inert placeholder and its subtree/inputs are never captured. The vendored rrweb bundle does not support rrweb's `ignoreSelector` (which only drops input *events*), so we map this knob onto the supported, stronger `blockSelector` to honor the "drop this field" intent. |
 
 Artifacts are two parallel POSTs per session, `kind ∈ {rrweb, video}`:
 
-- **rrweb** — gzipped JSON (`application/json+gzip`) — `{ run_id, session, event_count, events: [...] }`. DOM mutations + input events captured from every page; defaults mask all inputs for PII.
+- **rrweb** — gzipped JSON (`application/json+gzip`) — `{ run_id, session, event_count, events: [...] }`. DOM mutations + input events captured from every page.
+
+  **PII scope — read this.** `maskAllInputs` (on by default) only redacts the *values* a user types into form fields. It does **not** mask field labels, placeholders, `aria-label`s, `<option>` text, or any other rendered text, and it does not alter the recorded DOM structure. A displayed account number, balance, or name that is page text — not an input value — is captured verbatim. For those, point rrweb at the sensitive nodes with `WB_RECORDING_MASK_TEXT_SELECTOR` (mask the text) or `WB_RECORDING_BLOCK_SELECTOR` (omit the subtree). `WB_RECORDING_IGNORE_SELECTOR` is treated as an alias for `WB_RECORDING_BLOCK_SELECTOR` in this build (the vendored rrweb bundle has no `ignoreSelector` support), so a field named there is excluded from the recording entirely rather than merely having its input events dropped. When in doubt, block the region.
 - **video** — VP9 WebM (`video/webm`) — encoded from JPEG screencast frames via `ffmpeg`. Requires `ffmpeg` on `$PATH` (droplet install: `apt-get install -y ffmpeg`). If `ffmpeg` is missing the video kind silently disables and rrweb continues alone.
 
 Each POST carries headers `Authorization: Bearer <secret>`,
@@ -208,7 +216,7 @@ example, see the `browserbase-hn-upvoted-probe` runbook in the xatabase repo.
 | `assert`     | `assert: <selector>`        | `selector`, `text_contains`, `url_contains`     |
 | `eval`       | `eval: <js>`                | `script`                                        |
 | `save`       | `save: <name>`              | `name`, `value` (captures prior `extract`/`eval` when omitted) |
-| `download`   | `download: <selector>`      | `selector`, `path`, `timeout`, `text_fallback` (clicks + races Playwright `download` event with in-page blob/anchor capture; saves into `$WB_ARTIFACTS_DIR/<path>`) |
+| `download`   | `download: <selector>`      | `selector`, `path`, `timeout`, `text_fallback`, `signed_url` (clicks + races Playwright `download` event, in-page blob/anchor capture, and signed-URL export capture; saves into `$WB_ARTIFACTS_DIR/<path>`) |
 
 `extract`'s `fields` entries are either a CSS selector string (returns
 `textContent`), or `{ selector, attr }` to read an attribute.
@@ -308,9 +316,55 @@ Behaviour:
   doesn't double-save.
 - Emits `slice.artifact_saved` with `source: "download"` and
   `provenance.verb_name: "download"`.
-- On timeout: throws with diagnostics (page URL, selector, both
+- On timeout: throws with diagnostics (page URL, selector, all
   failure reasons) AND emits a `slice.download_failed` frame.
 
+#### Signed-URL export capture
+
+Some SaaS "Download" buttons never trip a Playwright `download` event or an
+in-page Blob. Instead the click calls a same-origin API that returns JSON like
+`{ "download_url": "https://bucket.s3.amazonaws.com/…?<signed>" }` and then
+navigates to that URL — and a page-side `fetch(signedUrl)` fails because the
+object store's CORS policy won't let the app origin read the bytes.
+
+The `download:` verb adds a **third** capture racer for this: it wraps the
+page's `fetch`/`XHR` around the click, inspects small same-origin JSON
+responses for URL-looking fields, and when it finds one pointing at a
+recognized object-store host (S3, GCS, CloudFront, Azure Blob, R2), it
+downloads the bytes **from the sidecar process** (where CORS doesn't apply)
+and saves them like any other artifact.
+
+This is **on by default in `auto` mode** — it only fires when a recognized
+signed host appears in a JSON response around the click, so a normal
+Playwright/blob download is unaffected. Tune or disable it per verb:
+
+```yaml
+- download:
+    selector: 'button:has-text("Download as xlsx")'
+    path: pilot-profit-loss.xlsx
+    timeout: 10s
+    signed_url:
+      enabled: true          # true | false | auto (default auto)
+      hosts:                 # extra non-recognized hosts to accept
+        - pilot-report-downloads.s3.amazonaws.com
+      json_fields:           # restrict to these response field names
+        - download_url
+```
+
+- Set `signed_url: false` to turn the capture off entirely for a verb.
+- In `auto` mode only recognized object-store hosts (or an explicit `hosts:`
+  entry) are fetched. With `enabled: true` an explicit `hosts:`/`json_fields:`
+  match is honored even for an unrecognized host, since you named it.
+- The captured URL's **query string (where signed credentials live) is
+  redacted** everywhere it crosses the stdio boundary — `provenance.signed_url`
+  is `origin+path?<redacted>`; the full URL stays only in sidecar memory for the
+  fetch. Honors `WB_BROWSER_DOWNLOAD_EXTENSIONS`.
+- The saved frame carries `provenance.capture: "signed_url"` plus `api_url`,
+  `field`, `content_type`, and `content_disposition`.
+- A 403 on the signed URL (expired token) emits `slice.download_failed` with
+  `expired: true` and `http_status: 403` so the operator knows to shorten the
+  click→fetch gap.
+
 ## Protocol
 
 Line-framed JSON, one message per line, on stdin/stdout. `stderr` is treated as
@@ -321,9 +375,26 @@ opaque diagnostics by `wb` and printed dimmed to the user's terminal.
 ```
 wb  →  {"type": "hello", "wb_version": "...", "protocol": "wb-sidecar/1"}
 wb  ←  {"type": "ready", "runtime": "wb-browser-runtime", "version": "...",
-        "protocol": "wb-sidecar/1", "supports": ["goto", "click", "fill", ...]}
+        "protocol": "wb-sidecar/1", "min_protocol": "wb-sidecar/1",
+        "supports": ["goto", "click", "fill", ...],
+        "features": ["recording", "pause", "substitution",
+                     "substitution_escape", "download_capture",
+                     "signed_url_download"]}
 ```
 
+The `ready` frame advertises capabilities so a client can feature-detect
+without a hard-coded version→capability map:
+
+- `protocol` — the wire version this runtime speaks.
+- `min_protocol` — the oldest protocol version it can still interoperate with
+  (equal to `protocol` until a breaking frame change ships). A client speaking
+  an older protocol than `min_protocol` should refuse rather than guess.
+- `supports` — the per-verb list (derived from the verb registry).
+- `features` — coarse capability tokens above the verb list.
+
+`version` is read from `package.json` at boot, so it can never drift from the
+published version.
+
 ### Slice
 
 ```

package/bin/wb-browser-runtime.js

@@ -25,9 +25,7 @@
 
 import readline from "node:readline";
 import { chromium } from "playwright-core";
-import { readFileSync } from "node:fs";
 import { send, log } from "../lib/io.js";
-import { resolveInside } from "../lib/util.js";
 import { SessionManager } from "../lib/session-manager.js";
 import {
   RecordingManager,
@@ -40,9 +38,31 @@ import {
   classifyError,
 } from "../lib/failure.js";
 import { installDownloadCapture } from "../lib/download-capture.js";
+import { expand, scrubSecrets } from "../lib/substitution.js";
 import { SUPPORTS, runVerb, verbName } from "../verbs/index.js";
+import pkg from "../package.json" with { type: "json" };
+
+// Read the version from package.json so the `ready` frame can never drift from
+// the published version (it used to be a hand-maintained literal that fell out
+// of sync). Node >=24 supports JSON import attributes natively.
+const VERSION = pkg.version;
+
+// Protocol capability advertisement. `protocol` is the wire version we speak;
+// `min_protocol` is the oldest version a peer may speak and still interoperate
+// (we keep it equal to `protocol` until we ship a breaking frame change).
+// `features` is a coarse capability list above the per-verb `supports` array —
+// a client can feature-detect without hard-coding a version→capability map.
+const PROTOCOL = "wb-sidecar/1";
+const MIN_PROTOCOL = "wb-sidecar/1";
+const FEATURES = [
+  "recording", // rrweb DOM capture + CDP screencast video
+  "pause", // pause_for_human operator handoff
+  "substitution", // {{ env.X }} / {{ artifacts.X }}
+  "substitution_escape", // \{{ literal-brace escape
+  "download_capture", // passive + explicit download artifact capture
+  "signed_url_download", // server-side fetch of in-JSON signed export URLs
+];
 
-const VERSION = "0.8.0";
 const provider = getProvider();
 log(`[provider] ${provider.name}`);
 
@@ -158,108 +178,9 @@ async function ensureSession(name, { profile, restoreSession } = {}) {
     }
   });
 }
-// --- {{ env.X }} / {{ artifacts.X }} substitution --------------------------
-
-const ENV_RE = /\{\{\s*env\.([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
-// Artifact names are bare identifiers — no dots, no slashes. Anything more
-// exotic would invite path traversal once composed with WB_ARTIFACTS_DIR.
-const ARTIFACT_RE = /\{\{\s*artifacts\.([A-Za-z_][A-Za-z0-9_-]*)\s*\}\}/g;
-
-// Resolved once at module load. `warn` matches historical behavior
-// (log + empty string, runbook continues). `error` throws so a missing OTP
-// or env var fails the slice instead of silently sending an empty value
-// into a Playwright action. `empty` is the silent variant.
-const ON_MISSING = (() => {
-  const raw = (process.env.WB_SUBSTITUTION_ON_MISSING || "warn")
-    .trim()
-    .toLowerCase();
-  if (raw === "error" || raw === "empty" || raw === "warn") return raw;
-  log(
-    `[warn] WB_SUBSTITUTION_ON_MISSING=${raw} is not valid (warn|error|empty); defaulting to warn`,
-  );
-  return "warn";
-})();
-
-function handleMissingSubstitution(kind, name) {
-  const msg = `${kind}.${name} is not set`;
-  if (ON_MISSING === "error") {
-    throw new Error(`substitution: ${msg}`);
-  }
-  if (ON_MISSING === "warn") {
-    log(`[warn] ${msg}; substituting empty string`);
-  }
-  return "";
-}
-
-function readArtifactRaw(name) {
-  const dir = (process.env.WB_ARTIFACTS_DIR || "").trim();
-  if (!dir) {
-    log(`[warn] artifacts.${name} referenced but WB_ARTIFACTS_DIR is not set`);
-    return null;
-  }
-  for (const candidate of [`${name}.txt`, name]) {
-    const full = resolveInside(dir, candidate);
-    if (!full) continue;
-    try {
-      return readFileSync(full, "utf8").trimEnd();
-    } catch {
-      // try next candidate
-    }
-  }
-  return null;
-}
-
-function readArtifact(name, cache) {
-  if (cache && cache.has(name)) {
-    const hit = cache.get(name);
-    if (hit === null) return handleMissingSubstitution("artifacts", name);
-    return hit;
-  }
-  const v = readArtifactRaw(name);
-  if (cache) cache.set(name, v);
-  if (v === null) return handleMissingSubstitution("artifacts", name);
-  return v;
-}
-
-function expand(value, collected, artifactCache) {
-  if (typeof value === "string") {
-    return value
-      .replace(ENV_RE, (_, name) => {
-        const v = process.env[name];
-        if (v === undefined) return handleMissingSubstitution("env", name);
-        if (collected && v.length >= 3) collected.add(v);
-        return v;
-      })
-      .replace(ARTIFACT_RE, (_, name) => {
-        const v = readArtifact(name, artifactCache);
-        if (collected && v && v.length >= 3) collected.add(v);
-        return v;
-      });
-  }
-  if (Array.isArray(value))
-    return value.map((v) => expand(v, collected, artifactCache));
-  if (value && typeof value === "object") {
-    const out = {};
-    for (const [k, v] of Object.entries(value))
-      out[k] = expand(v, collected, artifactCache);
-    return out;
-  }
-  return value;
-}
-
-// Scrub any values that came from {{ env.X }} / {{ artifacts.X }} expansion
-// out of error messages before they cross the stdio boundary — Playwright and
-// fetch errors sometimes echo their inputs (URLs, script bodies, assertion
-// text) and those inputs may contain credentials.
-function scrubSecrets(msg, secrets) {
-  let out = String(msg == null ? "" : msg);
-  if (!secrets) return out;
-  for (const s of secrets) {
-    if (!s) continue;
-    out = out.split(s).join("«***»");
-  }
-  return out;
-}
+// {{ env.X }} / {{ artifacts.X }} substitution + `\{{` escape + secret scrubbing
+// live in lib/substitution.js (extracted so they're unit-testable without
+// booting the sidecar).
 
 // --- Slice handler ----------------------------------------------------------
 
@@ -559,8 +480,10 @@ rl.on("line", (line) => {
         type: "ready",
         runtime: "wb-browser-runtime",
         version: VERSION,
-        protocol: "wb-sidecar/1",
+        protocol: PROTOCOL,
+        min_protocol: MIN_PROTOCOL,
         supports: SUPPORTS,
+        features: FEATURES,
       });
       break;
     case "slice":

package/lib/http.js

@@ -1,3 +1,5 @@
+import dns from "node:dns";
+import { isIP } from "node:net";
 import { log } from "./io.js";
 
 export async function safeText(res) {
@@ -8,6 +10,138 @@ export async function safeText(res) {
   }
 }
 
+// --- Body-read timeout handoff ---------------------------------------------
+//
+// retryableFetch's AbortController timer normally fires until fetch() resolves
+// (headers received) and is then cleared in `finally`. That leaves the *body*
+// read unbounded: a server can dribble bytes forever after sending headers.
+//
+// `keepBodyTimeout: true` is an opt-in for callers that consume the body
+// themselves (the signed-URL download path). When set, on a successful (2xx)
+// response we do NOT clear the timer — instead we stash the timer + controller
+// in a WeakMap keyed by the Response so the caller can either:
+//   - releaseBodyTimeout(res): clear it once the body is fully consumed, or
+//   - abortBody(res): abort the in-flight body read (e.g. size cap tripped).
+// If the caller never releases, the timer still fires and aborts the socket,
+// so a hung body read can't wedge the process. Other callers (default
+// keepBodyTimeout=false) are unaffected — their timer is cleared as before.
+const bodyTimers = new WeakMap();
+
+export function releaseBodyTimeout(res) {
+  const entry = bodyTimers.get(res);
+  if (entry) {
+    clearTimeout(entry.timer);
+    bodyTimers.delete(res);
+  }
+}
+
+export function abortBody(res) {
+  const entry = bodyTimers.get(res);
+  if (entry) {
+    try {
+      entry.controller.abort();
+    } catch {}
+  }
+}
+
+// Best-effort cancel/drain of a response body so a non-OK or redirect response
+// doesn't leak the underlying socket while we throw or follow a redirect.
+export async function drainResponseBody(res) {
+  try {
+    if (res?.body?.cancel) {
+      await res.body.cancel();
+    } else if (res?.body) {
+      // Fall back to consuming it if cancel() isn't available.
+      await res.arrayBuffer().catch(() => {});
+    }
+  } catch {}
+}
+
+// --- SSRF guard: private/loopback/link-local IP detection ------------------
+
+function isPrivateIPv4(addr) {
+  const m = /^(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(addr);
+  if (!m) return false;
+  const a = Number(m[1]);
+  const b = Number(m[2]);
+  if (a === 0) return true; // 0.0.0.0/8 (includes the unspecified address)
+  if (a === 127) return true; // 127.0.0.0/8 loopback
+  if (a === 10) return true; // 10.0.0.0/8
+  if (a === 172 && b >= 16 && b <= 31) return true; // 172.16.0.0/12
+  if (a === 192 && b === 168) return true; // 192.168.0.0/16
+  if (a === 169 && b === 254) return true; // 169.254.0.0/16 link-local
+  return false;
+}
+
+function isPrivateIPv6(addr) {
+  let s = String(addr).toLowerCase();
+  const pct = s.indexOf("%");
+  if (pct >= 0) s = s.slice(0, pct); // strip zone id
+  if (s === "::1") return true; // loopback
+  if (s === "::") return true; // unspecified
+  // IPv4-mapped / IPv4-embedded (e.g. ::ffff:127.0.0.1, ::127.0.0.1)
+  const v4 = /:(\d+\.\d+\.\d+\.\d+)$/.exec(s);
+  if (v4 && isPrivateIPv4(v4[1])) return true;
+  const first = s.split(":")[0];
+  if (/^f[cd]/.test(first)) return true; // fc00::/7 unique-local
+  if (/^fe[89ab]/.test(first)) return true; // fe80::/10 link-local
+  return false;
+}
+
+// True if a literal IP address falls in a private/loopback/link-local range.
+export function isPrivateIp(addr) {
+  const fam = isIP(addr);
+  if (fam === 4) return isPrivateIPv4(addr);
+  if (fam === 6) return isPrivateIPv6(addr);
+  return false;
+}
+
+// Validate a single URL as an allowed download target. Applies the caller's
+// host allowlist (the SAME check used on the initial URL — this is what makes
+// redirect following safe) and, unless explicitly allowed, rejects any host
+// that is a private IP literal or resolves to one (DNS rebinding / SSRF).
+// Throws on rejection; resolves on success.
+export async function assertAllowedTarget(
+  urlStr,
+  { validateHost = null, allowPrivateIp = false } = {},
+) {
+  let u;
+  try {
+    u = new URL(urlStr);
+  } catch {
+    throw new Error(`blocked target: unparseable URL`);
+  }
+  if (u.protocol !== "http:" && u.protocol !== "https:") {
+    throw new Error(`blocked target: unsupported scheme "${u.protocol}"`);
+  }
+  const host = u.host.toLowerCase(); // includes port — matches the picker
+  const hostname = u.hostname.toLowerCase();
+  if (validateHost && !validateHost(host)) {
+    throw new Error(`blocked target: host not allowed: ${host}`);
+  }
+  if (allowPrivateIp) return;
+  if (isIP(hostname)) {
+    if (isPrivateIp(hostname)) {
+      throw new Error(`blocked target: private/loopback IP ${hostname}`);
+    }
+    return;
+  }
+  let results;
+  try {
+    results = await dns.promises.lookup(hostname, { all: true });
+  } catch (e) {
+    // Fail closed: a host we can't resolve isn't a host we should fetch.
+    throw new Error(`blocked target: could not resolve ${hostname}: ${e?.message || e}`);
+  }
+  for (const r of results) {
+    if (isPrivateIp(r.address)) {
+      throw new Error(
+        `blocked target: ${hostname} resolves to private/loopback IP ${r.address}`,
+      );
+    }
+  }
+}
+
 // Retry transient network + 5xx/429 failures with short exponential backoff.
 // Each attempt gets its own AbortController + timeout; caller-passed signals
 // are not plumbed through since we don't have a cancellation story above this
@@ -17,11 +151,15 @@ export async function safeText(res) {
 // `bodyFactory`, when set, is invoked per attempt to produce a fresh body —
 // required for streaming uploads where the previous attempt consumed the
 // stream. Takes precedence over opts.body.
+//
+// `keepBodyTimeout`, when set, hands the attempt's abort timer to the caller on
+// a successful (2xx) response instead of clearing it, so the body-read window
+// stays bounded. See releaseBodyTimeout / abortBody above.
 export async function retryableFetch(
   url,
   opts = {},
   label,
-  { timeoutMs = 30_000, bodyFactory = null } = {},
+  { timeoutMs = 30_000, bodyFactory = null, keepBodyTimeout = false } = {},
 ) {
   const delays = [100, 500];
   let lastErr = null;
@@ -36,6 +174,7 @@ export async function retryableFetch(
     }
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let handedOff = false;
     try {
       const fetchOpts = { ...opts, signal: controller.signal };
       if (bodyFactory) {
@@ -45,7 +184,14 @@ export async function retryableFetch(
         fetchOpts.duplex = "half";
       }
       const res = await fetch(url, fetchOpts);
-      if (res.ok) return res;
+      if (res.ok) {
+        if (keepBodyTimeout) {
+          // Keep the timer armed until the caller consumes the body.
+          handedOff = true;
+          bodyTimers.set(res, { timer, controller });
+        }
+        return res;
+      }
       if (res.status === 429 || (res.status >= 500 && res.status < 600)) {
         lastRes = res;
         continue;
@@ -55,9 +201,60 @@ export async function retryableFetch(
       lastErr = e;
       continue;
     } finally {
-      clearTimeout(timer);
+      if (!handedOff) clearTimeout(timer);
     }
   }
   if (lastRes) return lastRes;
   throw lastErr;
 }
+
+export const MAX_DOWNLOAD_REDIRECTS = 5;
+
+// Fetch a download target with manual redirect handling and an SSRF guard.
+// Every hop (the initial URL and each Location target) is re-validated with
+// assertAllowedTarget before it is fetched, so a 3xx to an unvalidated or
+// private host is rejected instead of silently followed. Redirect bodies are
+// drained between hops. Returns the final (non-redirect) Response; the caller
+// owns the body (use keepBodyTimeout semantics: releaseBodyTimeout when done).
+export async function guardedDownloadFetch(
+  url,
+  {
+    timeoutMs = 30_000,
+    validateHost = null,
+    allowPrivateIp = false,
+    maxRedirects = MAX_DOWNLOAD_REDIRECTS,
+    label,
+  } = {},
+) {
+  let current = url;
+  for (let hop = 0; ; hop++) {
+    await assertAllowedTarget(current, { validateHost, allowPrivateIp });
+    const res = await retryableFetch(
+      current,
+      { method: "GET", redirect: "manual" },
+      label,
+      { timeoutMs, keepBodyTimeout: true },
+    );
+    const status = res.status;
+    if (status >= 300 && status < 400) {
+      const loc = res.headers?.get?.("location");
+      if (loc) {
+        // A 3xx is not res.ok, so it was never handed off — its timer is
+        // already cleared. Drain the redirect body and re-validate the target.
+        await drainResponseBody(res);
+        if (hop >= maxRedirects) {
+          throw new Error(`too many redirects (> ${maxRedirects})`);
+        }
+        let next;
+        try {
+          next = new URL(loc, current).toString();
+        } catch {
+          throw new Error(`blocked target: unparseable redirect Location`);
+        }
+        current = next;
+        continue;
+      }
+    }
+    return res;
+  }
+}

package/lib/recording-manager.js

@@ -148,6 +148,44 @@ export function loadRecordingConfig() {
     kinds,
     rrwebSource,
     rrwebMaxEvents,
+    mask: loadMaskConfig(),
+  };
+}
+
+// rrweb's `maskAllInputs` only redacts input *values* — labels, placeholders,
+// aria-labels, option text, and the full DOM structure are still recorded. For
+// genuinely sensitive regions (a displayed SSN, an account balance) the author
+// must point rrweb at the offending nodes with a CSS selector. These knobs
+// expose rrweb's selector options without hard-coding them:
+//   WB_RECORDING_MASK_ALL_INPUTS  default on; set "0" to record input values
+//   WB_RECORDING_MASK_TEXT_SELECTOR  text content of matches → asterisks
+//   WB_RECORDING_BLOCK_SELECTOR      matches recorded as inert placeholders
+//   WB_RECORDING_IGNORE_SELECTOR     matches excluded from the recording
+//
+// Privacy note: the vendored `vendor/rrweb-record.min.js` bundle supports
+// `blockSelector` but NOT `ignoreSelector` — passing `ignoreSelector` to this
+// build is a silent no-op, so an operator relying on it to drop a sensitive
+// field would have that value recorded verbatim. To keep the "drop this field"
+// promise on the shipped binary, WB_RECORDING_IGNORE_SELECTOR is folded into the
+// (supported, and strictly stronger) `blockSelector`: a blocked element is not
+// recorded at all — its subtree and inputs are never captured. The env var name
+// is kept for compatibility; both selectors are unioned so neither is lost.
+export function loadMaskConfig() {
+  const sel = (name) => {
+    const v = (process.env[name] || "").trim();
+    return v || null;
+  };
+  // Comma-join the explicit block selector with the ignore selector so the
+  // ignore intent is honored via a mechanism the vendored bundle actually
+  // supports. Either, both, or neither may be set.
+  const blockParts = [
+    sel("WB_RECORDING_BLOCK_SELECTOR"),
+    sel("WB_RECORDING_IGNORE_SELECTOR"),
+  ].filter(Boolean);
+  return {
+    maskAllInputs: process.env.WB_RECORDING_MASK_ALL_INPUTS !== "0",
+    maskTextSelector: sel("WB_RECORDING_MASK_TEXT_SELECTOR"),
+    blockSelector: blockParts.length ? blockParts.join(", ") : null,
   };
 }
 
@@ -221,17 +259,30 @@ export class RecordingManager {
             for (const e of batch) pushRrweb(e);
           }
         });
+        // Build rrweb record options from the resolved mask config. Selector
+        // options are omitted entirely when unset so we don't pass `null` into
+        // rrweb (which would match nothing but still allocate a matcher).
+        const mask = cfg.mask || { maskAllInputs: true };
+        const recordOpts = {
+          maskAllInputs: mask.maskAllInputs !== false,
+        };
+        if (mask.maskTextSelector)
+          recordOpts.maskTextSelector = mask.maskTextSelector;
+        // `blockSelector` already folds in WB_RECORDING_IGNORE_SELECTOR (see
+        // loadMaskConfig). We never pass `ignoreSelector` — the vendored rrweb
+        // bundle does not support it, so it would be silently dropped.
+        if (mask.blockSelector) recordOpts.blockSelector = mask.blockSelector;
+        const recordOptsJson = JSON.stringify(recordOpts);
         const bootstrap = `
 ;(function(){
   if (window.__wbRrwebActive) return;
   window.__wbRrwebActive = true;
   window.__wbRrwebBuffer = [];
   try {
-    rrwebRecord({
+    rrwebRecord(Object.assign({
       emit: function(event){ window.__wbRrwebBuffer.push(event); },
-      sampling: { scroll: 150, media: 800, input: 'last' },
-      maskAllInputs: true
-    });
+      sampling: { scroll: 150, media: 800, input: 'last' }
+    }, ${recordOptsJson}));
   } catch (e) { /* rrweb unavailable on this page (e.g. chrome://) */ }
   var flush = function(){
     var buf = window.__wbRrwebBuffer;