test-proxy-recorder 0.3.8 → 0.4.0

package/README.md

@@ -37,6 +37,8 @@ Both can be used together or independently.
 - [Full-stack (SSR + browser) Quick Start](#full-stack-ssr--browser-quick-start)
 - [Browser-only / SPA / Extension Quick Start](#browser-only--spa--extension-quick-start)
 - [CLI](#cli)
+  - [Config file](#config-file)
+- [Secret redaction](#secret-redaction)
 - [Example Apps](#example-apps)
 - [Playwright Integration](#playwright-integration)
 - [Next.js Integration](#nextjs-integration)
@@ -221,11 +223,15 @@ CI now runs without any network access.
 test-proxy-recorder <target-url> [options]
 ```
 
-| Option         | Default        | Description                   |
-| -------------- | -------------- | ----------------------------- |
-| `<target-url>` | *(required)*   | Backend URL to proxy          |
-| `--port, -p`   | `8080`         | Proxy listen port             |
-| `--dir, -d`    | `./recordings` | Directory for recording files |
+| Option           | Default        | Description                         |
+| ---------------- | -------------- | ----------------------------------- |
+| `<target-url>`   | *(required)*   | Backend URL to proxy                |
+| `--port, -p`     | `8000`         | Proxy listen port                   |
+| `--dir, -d`      | `./recordings` | Directory for recording files       |
+| `--timeout, -t`  | `120000`       | Session auto-reset timeout (ms)     |
+| `--config, -c`   | *(auto)*       | Path to a config file (see below)   |
+
+Secrets are redacted from recordings by default — see [Secret redaction](#secret-redaction) for the `--no-redact`, `--redact-headers`, and `--redact-body` flags.
 
 ```bash
 # Examples
@@ -233,6 +239,141 @@ test-proxy-recorder http://localhost:8000
 test-proxy-recorder http://localhost:8000 --port 8100 --dir ./mocks
 ```
 
+### Scaffold the setup (`init`)
+
+One command wires test-proxy-recorder into a project:
+
+```bash
+npx test-proxy-recorder init http://localhost:3002 --port 8100 --dir ./e2e/recordings
+```
+
+It generates / edits, **non-destructively**:
+
+- `test-proxy-recorder.config.ts` — the proxy config (auto-discovered, so
+  `npx test-proxy-recorder` then needs no flags).
+- `playwright.config.ts` — adds a `webServer` pointing at the proxy's
+  `/__control` endpoint plus a `globalTeardown`. If you already have a Playwright
+  config it's **edited in place**; if you don't have Playwright at all, `init`
+  runs the Playwright CLI to set it up first (pass `--no-install` to skip).
+- `e2e/fixtures.ts` and `e2e/global-teardown.ts` — the per-test proxy fixture and
+  teardown.
+- `package.json` — adds `proxy`, `test:e2e`, and `test:e2e:record` scripts. If
+  you have a `dev` script it's wrapped: the original moves to `dev:app` and `dev`
+  becomes a `concurrently` command that runs the proxy alongside your app (so
+  `npm run dev` records while you develop). `concurrently` is added to
+  `devDependencies`.
+
+All arguments are optional and fall back to sensible defaults
+(`http://localhost:3000`, port `8100`, `./e2e/recordings`). Existing files and
+scripts are never overwritten unless you pass `--force`; a Playwright config that
+already defines a `webServer` is left untouched (with a note on what to add).
+
+The **one step it can't do for you** is routing your app's backend calls through
+the proxy — which env var holds your API base URL, and how you scope it to dev,
+is app-specific. `init` prints concrete instructions for this when it finishes:
+point that env var at `http://localhost:8100` **in dev/test only, never in
+production** (e.g. prefix the `dev:app` script, using `cross-env` on Windows).
+The proxy then forwards to your real backend while recording and serves
+recordings on replay.
+
+### Config file
+
+For anything beyond a couple of flags — especially body-redaction regexes — put the
+options in a config file instead. The proxy auto-discovers
+`test-proxy-recorder.config.{ts,js,mjs,cjs}` in the current directory, or pass
+`--config <path>` to point at one explicitly. `.ts` files work out of the box.
+
+```ts
+// test-proxy-recorder.config.ts
+import { defineConfig } from 'test-proxy-recorder';
+
+export default defineConfig({
+  target: 'http://localhost:3002',
+  port: 8100,
+  recordingsDir: './e2e/recordings',
+  timeout: 120_000,
+  redaction: {
+    headers: ['x-api-key'],         // extra headers, merged with the defaults
+    bodyPatterns: [/sk_live_\w+/g], // real RegExp literals — no CLI escaping
+    allowCookies: ['theme'],        // keep these cookies unredacted
+  },
+});
+```
+
+```bash
+test-proxy-recorder                 # all options from the config file
+test-proxy-recorder --port 9000     # config file, but CLI port wins
+```
+
+**Precedence:** every option resolves as **CLI flag → config file → built-in default**.
+A flag you pass on the command line always overrides the config file; anything you
+omit falls back to the config, then the default. (List flags like `--redact-headers`
+*replace* the config's list rather than merging — pass it only when you want to
+override.) `target` may be given as the CLI argument or as `target` in the config;
+the argument wins when both are present.
+
+---
+
+## Secret redaction
+
+<details>
+<summary>Secrets are stripped automatically by default — show details</summary>
+
+Recordings are meant to be committed to git, so secrets are stripped **automatically** before anything is written to disk. By default the proxy replaces the values of these request/response headers with `[REDACTED]`:
+
+- `Authorization`
+- `Cookie`
+- `Set-Cookie`
+
+This is safe: replay matching ignores these headers, so redaction never breaks playback. It applies to both `.mock.json` recordings and WebSocket recordings.
+
+When only *some* cookies are sensitive, allow-list the harmless ones by name (e.g. a `theme` or A/B-test cookie). Allow-listed cookies keep their values inside `Cookie`/`Set-Cookie`; every other cookie is still redacted.
+
+> **Note:** `.har` files (browser-side requests recorded via Playwright's `routeFromHAR`) are written by Playwright, not the proxy, so this redaction does not cover them. Keep tokens out of HAR by recording with short-lived test credentials and reviewing HARs before committing — see the recommended setup-auth pattern below.
+
+### Recommended auth pattern
+
+To keep the login flow and credentials out of recordings entirely, run authentication in a Playwright **setup project** with the proxy in `transparent` mode, persist `storageState` to a **gitignored** `auth-state.json`, and reuse it in your tests. Recorded requests then carry only the (redacted) session headers, never the login.
+
+### Tweaking what gets redacted
+
+The defaults always apply while redaction is enabled; you can add to them or turn it off.
+
+**CLI flags:**
+
+- `--redact-headers <names>` — comma-separated extra header names to redact (merged with the defaults).
+- `--redact-body <patterns>` — comma-separated regex patterns to redact from request/response bodies.
+- `--allow-headers <names>` — comma-separated header names to exempt from redaction (e.g. `set-cookie`).
+- `--allow-cookies <names>` — comma-separated cookie names to keep unredacted inside `Cookie`/`Set-Cookie`.
+- `--no-redact` — disable redaction and commit raw secrets (not recommended).
+
+```bash
+# Redact an API-key header and "sk_live_..." tokens, but keep the theme cookie
+test-proxy-recorder http://localhost:8000 \
+  --redact-headers x-api-key \
+  --redact-body "sk_live_[a-zA-Z0-9]+" \
+  --allow-cookies theme,locale
+```
+
+**Programmatic** (when constructing `ProxyServer` directly):
+
+```typescript
+import { ProxyServer } from 'test-proxy-recorder';
+
+const proxy = new ProxyServer('http://localhost:3000', './recordings', undefined, {
+  enabled: true,                       // default; set false to disable
+  headers: ['x-api-key', 'x-auth'],    // extra headers, merged with the defaults
+  bodyPatterns: [/sk_live_[a-z0-9]+/i], // regexes replaced in request/response bodies
+  allowHeaders: ['set-cookie'],        // never redact these headers
+  allowCookies: ['theme', 'locale'],   // keep these cookies inside Cookie/Set-Cookie
+  placeholder: '[REDACTED]',           // default
+});
+```
+
+`redactSession(session, config)` is also exported if you want to redact existing recordings yourself.
+
+</details>
+
 ---
 
 ## Example Apps
@@ -407,6 +548,23 @@ function setProxyMode(
 ): Promise<void>;
 ```
 
+### `defineConfig`
+
+Type-checked identity helper for a `test-proxy-recorder.config.{ts,js,mjs}` file
+(see [Config file](#config-file)).
+
+```typescript
+function defineConfig(config: Config): Config;
+
+interface Config {
+  target?: string;
+  port?: number;
+  recordingsDir?: string;
+  timeout?: number;
+  redaction?: RedactionConfig;
+}
+```
+
 ### Next.js helpers (`test-proxy-recorder/nextjs`)
 
 ```typescript

package/dist/{index-BloXCw69.d.cts → index-BnkejxM_.d.cts}

@@ -122,4 +122,4 @@ declare const playwrightProxy: {
     teardown(): Promise<void>;
 };
 
-export { type ControlRequest as C, type Mode as M, type PlaywrightTestInfo as P, type Recording as R, type WebSocketRecording as W, type RecordingSession as a, startRecording as b, startReplay as c, stopProxy as d, cleanupSession as e, type ClientSideRecordingOptions as f, generateSessionId as g, playwrightProxy as p, setProxyMode as s };
+export { type ControlRequest as C, type Mode as M, type PlaywrightTestInfo as P, type RecordingSession as R, type WebSocketRecording as W, type Recording as a, startRecording as b, startReplay as c, stopProxy as d, cleanupSession as e, type ClientSideRecordingOptions as f, generateSessionId as g, playwrightProxy as p, setProxyMode as s };

package/dist/{index-BloXCw69.d.ts → index-BnkejxM_.d.ts}

@@ -122,4 +122,4 @@ declare const playwrightProxy: {
     teardown(): Promise<void>;
 };
 
-export { type ControlRequest as C, type Mode as M, type PlaywrightTestInfo as P, type Recording as R, type WebSocketRecording as W, type RecordingSession as a, startRecording as b, startReplay as c, stopProxy as d, cleanupSession as e, type ClientSideRecordingOptions as f, generateSessionId as g, playwrightProxy as p, setProxyMode as s };
+export { type ControlRequest as C, type Mode as M, type PlaywrightTestInfo as P, type RecordingSession as R, type WebSocketRecording as W, type Recording as a, startRecording as b, startReplay as c, stopProxy as d, cleanupSession as e, type ClientSideRecordingOptions as f, generateSessionId as g, playwrightProxy as p, setProxyMode as s };

package/dist/index.cjs

@@ -19,6 +19,11 @@ var crypto__default = /*#__PURE__*/_interopDefault(crypto);
 var path2__default = /*#__PURE__*/_interopDefault(path2);
 var filenamify2__default = /*#__PURE__*/_interopDefault(filenamify2);
 
+// src/config.ts
+function defineConfig(config) {
+  return config;
+}
+
 // src/constants.ts
 var DEFAULT_TIMEOUT_MS = 120 * 1e3;
 var HTTP_STATUS_BAD_GATEWAY = 502;
@@ -272,6 +277,139 @@ var Modes = {
   record: "record",
   replay: "replay"
 };
+
+// src/utils/redact.ts
+var DEFAULT_REDACTED_HEADERS = [
+  "authorization",
+  "cookie",
+  "set-cookie"
+];
+var REDACTED_PLACEHOLDER = "[REDACTED]";
+var COOKIE_HEADERS = /* @__PURE__ */ new Set(["cookie", "set-cookie"]);
+function resolveRedaction(config) {
+  const extra = (config?.headers ?? []).map((name) => name.toLowerCase());
+  const headerSet = /* @__PURE__ */ new Set([...DEFAULT_REDACTED_HEADERS, ...extra]);
+  for (const name of config?.allowHeaders ?? []) {
+    headerSet.delete(name.toLowerCase());
+  }
+  return {
+    headerSet,
+    allowCookies: new Set(
+      (config?.allowCookies ?? []).map((name) => name.toLowerCase())
+    ),
+    regexes: toGlobalRegexes(config?.bodyPatterns),
+    placeholder: config?.placeholder ?? REDACTED_PLACEHOLDER
+  };
+}
+function toGlobalRegexes(patterns) {
+  if (!patterns || patterns.length === 0) {
+    return [];
+  }
+  return patterns.map((pattern) => {
+    if (typeof pattern === "string") {
+      return new RegExp(pattern, "g");
+    }
+    return pattern.flags.includes("g") ? pattern : new RegExp(pattern.source, `${pattern.flags}g`);
+  });
+}
+function redactCookieHeader(value, allowCookies, placeholder) {
+  return value.split(";").map((part) => part.trim()).filter(Boolean).map((pair) => {
+    const eq = pair.indexOf("=");
+    if (eq === -1) {
+      return pair;
+    }
+    const name = pair.slice(0, eq);
+    return allowCookies.has(name.toLowerCase()) ? pair : `${name}=${placeholder}`;
+  }).join("; ");
+}
+function redactSetCookieValue(value, allowCookies, placeholder) {
+  const semicolon = value.indexOf(";");
+  const firstPair = semicolon === -1 ? value : value.slice(0, semicolon);
+  const attributes = semicolon === -1 ? "" : value.slice(semicolon);
+  const eq = firstPair.indexOf("=");
+  if (eq === -1) {
+    return value;
+  }
+  const name = firstPair.slice(0, eq).trim();
+  if (allowCookies.has(name.toLowerCase())) {
+    return value;
+  }
+  return `${name}=${placeholder}${attributes}`;
+}
+function redactCookieAware(lower, value, resolved) {
+  const { allowCookies, placeholder } = resolved;
+  const redactOne = (cookie) => lower === "cookie" ? redactCookieHeader(cookie, allowCookies, placeholder) : redactSetCookieValue(cookie, allowCookies, placeholder);
+  return Array.isArray(value) ? value.map((v) => redactOne(v)) : redactOne(String(value));
+}
+function redactHeaderValue(name, value, resolved) {
+  const lower = name.toLowerCase();
+  if (resolved.allowCookies.size > 0 && COOKIE_HEADERS.has(lower)) {
+    return redactCookieAware(lower, value, resolved);
+  }
+  return Array.isArray(value) ? value.map(() => resolved.placeholder) : resolved.placeholder;
+}
+function redactHeaders(headers, resolved) {
+  const result = {};
+  for (const [name, value] of Object.entries(headers)) {
+    result[name] = resolved.headerSet.has(name.toLowerCase()) ? redactHeaderValue(name, value, resolved) : value;
+  }
+  return result;
+}
+function redactBody(body, regexes, placeholder) {
+  if (!body || regexes.length === 0) {
+    return body ?? null;
+  }
+  let result = body;
+  for (const regex of regexes) {
+    regex.lastIndex = 0;
+    result = result.replace(regex, placeholder);
+  }
+  return result;
+}
+function redactRecording(recording, resolved) {
+  const { regexes, placeholder } = resolved;
+  return {
+    ...recording,
+    request: {
+      ...recording.request,
+      headers: redactHeaders(recording.request.headers, resolved),
+      body: redactBody(recording.request.body, regexes, placeholder)
+    },
+    response: recording.response && {
+      ...recording.response,
+      headers: redactHeaders(recording.response.headers, resolved),
+      body: redactBody(recording.response.body, regexes, placeholder)
+    }
+  };
+}
+function redactWebSocketRecording(recording, resolved) {
+  const { regexes, placeholder } = resolved;
+  return {
+    ...recording,
+    headers: recording.headers ? redactHeaders(recording.headers, resolved) : recording.headers,
+    messages: recording.messages.map((message) => ({
+      ...message,
+      data: redactBody(message.data, regexes, placeholder) ?? message.data
+    }))
+  };
+}
+function redactSession(session, config) {
+  if (config?.enabled === false) {
+    return session;
+  }
+  const resolved = resolveRedaction(config);
+  return {
+    ...session,
+    recordings: session.recordings.map(
+      (recording) => redactRecording(recording, resolved)
+    ),
+    websocketRecordings: (session.websocketRecordings ?? []).map(
+      (recording) => redactWebSocketRecording(recording, resolved)
+    )
+  };
+}
+
+// src/utils/fileUtils.ts
 var JSON_INDENT_SPACES = 2;
 var EXTENSION = ".mock.json";
 var MAX_FILENAME_LENGTH = 255 - EXTENSION.length;
@@ -316,14 +454,17 @@ function processRecordings(recordings) {
   processedRecordings.sort((a, b) => a.recordingId - b.recordingId);
   return processedRecordings;
 }
-async function saveRecordingSession(recordingsDir, session) {
+async function saveRecordingSession(recordingsDir, session, redaction) {
   const filePath = getRecordingPath(recordingsDir, session.id);
   await fs__default.default.mkdir(recordingsDir, { recursive: true });
   const processedRecordings = processRecordings(session.recordings);
-  const processedSession = {
-    ...session,
-    recordings: processedRecordings
-  };
+  const processedSession = redactSession(
+    {
+      ...session,
+      recordings: processedRecordings
+    },
+    redaction
+  );
   await fs__default.default.writeFile(
     filePath,
     JSON.stringify(processedSession, null, JSON_INDENT_SPACES)
@@ -552,19 +693,22 @@ var ProxyServer = class {
   currentSession;
   recordingsDir;
   timeoutMs;
-  recordingIdCounter;
   // Unique ID for each recording entry
-  sequenceCounterByKey;
+  recordingIdCounter;
   // Sequence counter per key (endpoint)
+  sequenceCounterByKey;
   replaySessions;
   // Track multiple concurrent replay sessions by recording ID
   recordingPromises;
   // Stack of promises that resolve to completed recordings
   flushPromise;
   // Promise for in-progress flush operation
-  constructor(target, recordingsDir, timeoutMs) {
+  redaction;
+  // Secret-redaction config applied before saving
+  constructor(target, recordingsDir, timeoutMs, redaction) {
     this.target = target;
     this.timeoutMs = timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.redaction = redaction;
     this.mode = Modes.transparent;
     this.recordingId = null;
     this.recordingIdCounter = 0;
@@ -814,7 +958,11 @@ var ProxyServer = class {
     console.log(
       `Saving session with ${this.currentSession.recordings.length} HTTP and ${this.currentSession.websocketRecordings.length} WebSocket recordings`
     );
-    await saveRecordingSession(this.recordingsDir, this.currentSession);
+    await saveRecordingSession(
+      this.recordingsDir,
+      this.currentSession,
+      this.redaction
+    );
   }
   getRecordingIdOrError(req, res) {
     const recordingIdFromRequest = getRecordingIdFromRequest(req);
@@ -1318,12 +1466,16 @@ function createHeadersWithRecordingId(requestHeaders, additionalHeaders = {}) {
   };
 }
 
+exports.DEFAULT_REDACTED_HEADERS = DEFAULT_REDACTED_HEADERS;
 exports.ProxyServer = ProxyServer;
 exports.RECORDING_ID_HEADER = RECORDING_ID_HEADER;
+exports.REDACTED_PLACEHOLDER = REDACTED_PLACEHOLDER;
 exports.createHeadersWithRecordingId = createHeadersWithRecordingId;
+exports.defineConfig = defineConfig;
 exports.generateSessionId = generateSessionId;
 exports.getRecordingId = getRecordingId;
 exports.playwrightProxy = playwrightProxy;
+exports.redactSession = redactSession;
 exports.setNextProxyHeaders = setNextProxyHeaders;
 exports.setProxyMode = setProxyMode;
 exports.startRecording = startRecording;

package/dist/index.d.cts

@@ -1,8 +1,92 @@
+import { R as RecordingSession } from './index-BnkejxM_.cjs';
+export { C as ControlRequest, M as Mode, P as PlaywrightTestInfo, a as Recording, W as WebSocketRecording, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from './index-BnkejxM_.cjs';
 export { RECORDING_ID_HEADER, createHeadersWithRecordingId, getRecordingId, setNextProxyHeaders } from './nextjs/index.cjs';
 import http from 'node:http';
-export { C as ControlRequest, M as Mode, P as PlaywrightTestInfo, R as Recording, a as RecordingSession, W as WebSocketRecording, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from './index-BloXCw69.cjs';
 import '@playwright/test';
 
+/**
+ * Header names (lower-cased) whose values are stripped from recordings by
+ * default. These commonly carry credentials and are safe to remove: replay
+ * matching ignores request/response headers, so redaction never breaks
+ * playback.
+ */
+declare const DEFAULT_REDACTED_HEADERS: string[];
+/** Value written in place of a redacted secret. */
+declare const REDACTED_PLACEHOLDER = "[REDACTED]";
+interface RedactionConfig {
+    /**
+     * Master switch. Redaction is on by default; set to `false` to commit raw
+     * headers and bodies (not recommended).
+     */
+    enabled?: boolean;
+    /**
+     * Additional header names (case-insensitive) to redact. Merged with
+     * {@link DEFAULT_REDACTED_HEADERS} — the defaults always apply while
+     * enabled.
+     */
+    headers?: string[];
+    /**
+     * Header names (case-insensitive) to leave untouched even if they would
+     * otherwise be redacted. Use to exempt a header from the defaults, e.g.
+     * `['set-cookie']` when no session cookie is set on responses.
+     */
+    allowHeaders?: string[];
+    /**
+     * Cookie names (case-insensitive) to keep unredacted inside the `Cookie`
+     * and `Set-Cookie` headers. Every other cookie in those headers still has
+     * its value replaced. Use this when only some cookies are sensitive — e.g.
+     * keep a `theme` or A/B-test cookie while redacting the session cookie.
+     */
+    allowCookies?: string[];
+    /**
+     * Patterns matched against request/response bodies (and WebSocket message
+     * payloads). Every match is replaced with the placeholder. Strings are
+     * treated as global regular expressions. Use this for API keys or tokens
+     * embedded in payloads.
+     */
+    bodyPatterns?: (RegExp | string)[];
+    /** Replacement string. Defaults to {@link REDACTED_PLACEHOLDER}. */
+    placeholder?: string;
+}
+/**
+ * Return a redacted copy of a recording session. Sensitive headers are
+ * stripped and any configured body patterns replaced. The input is not
+ * mutated. When `config.enabled === false` the session is returned unchanged.
+ */
+declare function redactSession(session: RecordingSession, config?: RedactionConfig): RecordingSession;
+
+/**
+ * Shape of a `test-proxy-recorder.config.{ts,js,mjs}` file. Every field is
+ * optional; any value passed as a CLI flag overrides the matching config value.
+ */
+interface Config {
+    /** Target API service URL, e.g. `http://localhost:3000`. */
+    target?: string;
+    /** Port for the proxy server. */
+    port?: number;
+    /** Directory to store recordings, resolved relative to CWD. */
+    recordingsDir?: string;
+    /** Session timeout in milliseconds. */
+    timeout?: number;
+    /** Secret redaction settings. See {@link RedactionConfig}. */
+    redaction?: RedactionConfig;
+}
+/**
+ * Identity helper for config files. Wrapping the object gives type-checking and
+ * editor autocomplete without changing its value:
+ *
+ * ```ts
+ * // test-proxy-recorder.config.ts
+ * import { defineConfig } from 'test-proxy-recorder';
+ *
+ * export default defineConfig({
+ *   target: 'http://localhost:3000',
+ *   redaction: { bodyPatterns: [/sk_live_\w+/g] },
+ * });
+ * ```
+ */
+declare function defineConfig(config: Config): Config;
+
 declare class ProxyServer {
     private target;
     private mode;
@@ -18,7 +102,8 @@ declare class ProxyServer {
     private replaySessions;
     private recordingPromises;
     private flushPromise;
-    constructor(target: string, recordingsDir: string, timeoutMs?: number);
+    private redaction?;
+    constructor(target: string, recordingsDir: string, timeoutMs?: number, redaction?: RedactionConfig);
     init(): Promise<void>;
     listen(port: number): http.Server;
     private setupProxyEventHandlers;
@@ -60,4 +145,4 @@ declare class ProxyServer {
     private logServerStartup;
 }
 
-export { ProxyServer };
+export { type Config, DEFAULT_REDACTED_HEADERS, ProxyServer, REDACTED_PLACEHOLDER, RecordingSession, type RedactionConfig, defineConfig, redactSession };

package/dist/index.d.ts

@@ -1,8 +1,92 @@
+import { R as RecordingSession } from './index-BnkejxM_.js';
+export { C as ControlRequest, M as Mode, P as PlaywrightTestInfo, a as Recording, W as WebSocketRecording, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from './index-BnkejxM_.js';
 export { RECORDING_ID_HEADER, createHeadersWithRecordingId, getRecordingId, setNextProxyHeaders } from './nextjs/index.js';
 import http from 'node:http';
-export { C as ControlRequest, M as Mode, P as PlaywrightTestInfo, R as Recording, a as RecordingSession, W as WebSocketRecording, g as generateSessionId, p as playwrightProxy, s as setProxyMode, b as startRecording, c as startReplay, d as stopProxy } from './index-BloXCw69.js';
 import '@playwright/test';
 
+/**
+ * Header names (lower-cased) whose values are stripped from recordings by
+ * default. These commonly carry credentials and are safe to remove: replay
+ * matching ignores request/response headers, so redaction never breaks
+ * playback.
+ */
+declare const DEFAULT_REDACTED_HEADERS: string[];
+/** Value written in place of a redacted secret. */
+declare const REDACTED_PLACEHOLDER = "[REDACTED]";
+interface RedactionConfig {
+    /**
+     * Master switch. Redaction is on by default; set to `false` to commit raw
+     * headers and bodies (not recommended).
+     */
+    enabled?: boolean;
+    /**
+     * Additional header names (case-insensitive) to redact. Merged with
+     * {@link DEFAULT_REDACTED_HEADERS} — the defaults always apply while
+     * enabled.
+     */
+    headers?: string[];
+    /**
+     * Header names (case-insensitive) to leave untouched even if they would
+     * otherwise be redacted. Use to exempt a header from the defaults, e.g.
+     * `['set-cookie']` when no session cookie is set on responses.
+     */
+    allowHeaders?: string[];
+    /**
+     * Cookie names (case-insensitive) to keep unredacted inside the `Cookie`
+     * and `Set-Cookie` headers. Every other cookie in those headers still has
+     * its value replaced. Use this when only some cookies are sensitive — e.g.
+     * keep a `theme` or A/B-test cookie while redacting the session cookie.
+     */
+    allowCookies?: string[];
+    /**
+     * Patterns matched against request/response bodies (and WebSocket message
+     * payloads). Every match is replaced with the placeholder. Strings are
+     * treated as global regular expressions. Use this for API keys or tokens
+     * embedded in payloads.
+     */
+    bodyPatterns?: (RegExp | string)[];
+    /** Replacement string. Defaults to {@link REDACTED_PLACEHOLDER}. */
+    placeholder?: string;
+}
+/**
+ * Return a redacted copy of a recording session. Sensitive headers are
+ * stripped and any configured body patterns replaced. The input is not
+ * mutated. When `config.enabled === false` the session is returned unchanged.
+ */
+declare function redactSession(session: RecordingSession, config?: RedactionConfig): RecordingSession;
+
+/**
+ * Shape of a `test-proxy-recorder.config.{ts,js,mjs}` file. Every field is
+ * optional; any value passed as a CLI flag overrides the matching config value.
+ */
+interface Config {
+    /** Target API service URL, e.g. `http://localhost:3000`. */
+    target?: string;
+    /** Port for the proxy server. */
+    port?: number;
+    /** Directory to store recordings, resolved relative to CWD. */
+    recordingsDir?: string;
+    /** Session timeout in milliseconds. */
+    timeout?: number;
+    /** Secret redaction settings. See {@link RedactionConfig}. */
+    redaction?: RedactionConfig;
+}
+/**
+ * Identity helper for config files. Wrapping the object gives type-checking and
+ * editor autocomplete without changing its value:
+ *
+ * ```ts
+ * // test-proxy-recorder.config.ts
+ * import { defineConfig } from 'test-proxy-recorder';
+ *
+ * export default defineConfig({
+ *   target: 'http://localhost:3000',
+ *   redaction: { bodyPatterns: [/sk_live_\w+/g] },
+ * });
+ * ```
+ */
+declare function defineConfig(config: Config): Config;
+
 declare class ProxyServer {
     private target;
     private mode;
@@ -18,7 +102,8 @@ declare class ProxyServer {
     private replaySessions;
     private recordingPromises;
     private flushPromise;
-    constructor(target: string, recordingsDir: string, timeoutMs?: number);
+    private redaction?;
+    constructor(target: string, recordingsDir: string, timeoutMs?: number, redaction?: RedactionConfig);
     init(): Promise<void>;
     listen(port: number): http.Server;
     private setupProxyEventHandlers;
@@ -60,4 +145,4 @@ declare class ProxyServer {
     private logServerStartup;
 }
 
-export { ProxyServer };
+export { type Config, DEFAULT_REDACTED_HEADERS, ProxyServer, REDACTED_PLACEHOLDER, RecordingSession, type RedactionConfig, defineConfig, redactSession };