Repository navigation
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.
- A scenario never contains a secret. A
fillstep 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" } }-
Schema.
filltakes exactly one ofvalueorvalueFrom. The variable name must match^[A-Z_][A-Z0-9_]*$. -
Readiness. Before the browser launches, every
valueFrom.envis read from the process environment. A missing or empty variable fails thereadinessstage withmissing-env NAMEand the step's index; the run exits with code 2 and no browser starts. -
Typing. The engine types the value into the field and measures the field's box. The timeline event gets
masked: trueandvalue: "***". -
Visibility tracking. After every later step the engine checks whether the field is still on the page. The event's
maskVisibilitylists 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. -
Failure. If the masked
fillitself 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. -
Scrubbing. Every error message the engine writes is passed through a scrubber that replaces each secret's text with
***. - 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"]
Write the scenario with valueFrom, then set the variable for the run:
DEMO_PASSWORD='…' npx demoflow run demoflow/login.demo.jsonOn Windows PowerShell:
$env:DEMO_PASSWORD = '…'; npx demoflow run demoflow/login.demo.jsonIn 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.
| 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.
- A secret is never written to the scenario,
timeline.json,result.jsonor 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.webmin the run directory is the raw recording of the page, and ascreenshotstep saves the page as it is. A password input shows dots there; a plain text field filled fromvalueFromshows what was typed. Treat the run directory as sensitive. - Only fields filled from
valueFromare 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.
-
Scenarios — the
fillstep - Recording Scenarios — Secret next and password fields
- Run Artifacts — what is in the run directory
- Rendering and Effects · Security and Access
- ADR-0003: scenario format and project config · ADR-0004: recording is separate from rendering
- Spec 18: mask visibility · Spec 42: masked fill failure
DemoFlow · Issues · Decision records · Specs · MIT licensed
Start
Features
- Scenarios
- Recording Scenarios
- Running Demos
- Rendering and Effects
- Secrets and Masking
- Run Artifacts
- MCP Server
Operate
Reference