Skip to content

Secrets and Masking

Archi edited this page Oct 18, 2026 · 1 revision

Secrets and Masking

A demo often has to sign in. DemoFlow keeps the password out of the scenario and the run's text files, and blurs the field in the rendered video.

Overview

  • A scenario never contains a secret. A fill step names an environment variable instead: "valueFrom": { "env": "DEMO_PASSWORD" }.
  • Before the browser starts, every such variable must be set and non-empty, or the run stops with missing-env NAME.
  • The engine types the secret into the page and records the step as masked: the timeline holds ***, never the value.
  • Error messages are scrubbed: the secret's text is replaced with ***.
  • The renderer blurs the field's box for as long as the field is on the page, with a safety margin in space and time.
{ "action": "fill", "target": { "label": "Password" }, "valueFrom": { "env": "DEMO_PASSWORD" } }

How it works

  1. Schema. fill takes exactly one of value or valueFrom. The variable name must match ^[A-Z_][A-Z0-9_]*$.
  2. Readiness. Before the browser launches, every valueFrom.env is read from the process environment. A missing or empty variable fails the readiness stage with missing-env NAME and the step's index; the run exits with code 2 and no browser starts.
  3. Typing. The engine types the value into the field and measures the field's box. The timeline event gets masked: true and value: "***".
  4. Visibility tracking. After every later step the engine checks whether the field is still on the page. The event's maskVisibility lists the intervals when it was, each with its box: a navigation or the field disappearing ends an interval; the field coming back starts a new one. Scrolling it out of the viewport does not end an interval, since it may scroll back.
  5. Failure. If the masked fill itself fails part-way, its event is still masked and only the first line of Playwright's error is kept, so a page that mirrors the typed text into an attribute cannot leak it through the error. If the field could not be measured at all, the whole viewport is blurred from that point to the end of the video.
  6. Scrubbing. Every error message the engine writes is passed through a scrubber that replaces each secret's text with ***.
  7. Rendering. The renderer draws a blurred box over each interval: the box grows by 4 px on every side, starts 200 ms early and ends 200 ms late. When the clock offset between the video and the timeline has been measured, the lead and trail shrink to one source frame. Page scrolls during an interval move the box with the page. The blur follows the camera's zoom and the window frame.
flowchart TD
  S["fill with valueFrom.env"] --> R{"Variable set<br/>and non-empty?"}
  R -- no --> X["readiness failed:<br/>missing-env NAME, exit 2"]
  R -- yes --> T["Engine types the value"]
  T --> E["timeline event:<br/>masked: true, value: ***"]
  E --> V["maskVisibility intervals<br/>after every step"]
  V --> B["Renderer blurs the box<br/>+4 px, 200 ms lead and trail"]
Loading

Using it

Write the scenario with valueFrom, then set the variable for the run:

DEMO_PASSWORD='…' npx demoflow run demoflow/login.demo.json

On Windows PowerShell:

$env:DEMO_PASSWORD = '…'; npx demoflow run demoflow/login.demo.json

In CI, read the variable from the CI's secret store. The repository's own execution-plane workflow does this for the fixture's sign-in scenario with a generated FIXTURE_PASSWORD.

When recording, a password field is captured as valueFrom automatically. For any other field, click Secret next in the recording panel before typing; the variable name comes from the Secret variable field, DEMO_PASSWORD by default. See Recording Scenarios.

In timeline.json, a masked step looks like this (other fields left out):

{
  "action": "fill",
  "masked": true,
  "value": "***",
  "maskVisibility": [{ "startMs": 2140, "endMs": 3980, "box": { "x": 480, "y": 312, "width": 320, "height": 40 } }]
}

The timeline schema rejects a masked event whose value is anything but ***, and maskVisibility on an event that is not masked.

Settings

Setting Value Where
Variable name pattern ^[A-Z_][A-Z0-9_]*$ scenario schema
Mask margin 4 px on every side renderer
Mask lead / trail 200 ms each; one source frame when the offset is measured renderer
Recorder default variable DEMO_PASSWORD demoflow record

None of these are configurable in demoflow.config.json.

Limits / what it never does

  • A secret is never written to the scenario, timeline.json, result.json or the console by DemoFlow.
  • It never runs with a missing secret: an unset or empty variable stops the run before the browser starts.
  • Masking applies to the rendered video only. source.webm in the run directory is the raw recording of the page, and a screenshot step saves the page as it is. A password input shows dots there; a plain text field filled from valueFrom shows what was typed. Treat the run directory as sensitive.
  • Only fields filled from valueFrom are masked. Other sensitive content on the page is not detected.
  • It does not mask inside scroll containers by following them: a container scroll does not move the box.

Warning

Do not share a run directory as if it were the video. Share render/ffmpeg.mp4.

See also

Clone this wiki locally