Repository navigation
secrets and scope
An operator puts secrets on the server, and a caller types one into a page by name. The value never comes back to the caller. This area covers where secrets come from, how each names the sites it may be typed on, how one is bound to a write, and how every result, resource, log line and error is kept free of the values of the secrets allowed on the site it came from, typed or not.
- An operator mounts a Kubernetes Secret and adds one
_allowed_urlsfile. An agent signs in withwrite(secret={"name": ..., "key": ...}), and neither its transcript nor any result holds the password. - An agent reads a page that echoes the password. The echo comes back as
[secret:name/key], which reads straight back as the argument towrite. - A person types a catalogued password in the live view, and a later
extractof that page is scrubbed. The scrub does not depend on this server having typed the value. - An operator rotates a mounted key. Within the catalogue's 30 seconds, results are scrubbed with the new value, and the old one stays masked until the browser ends.
- An operator sees a secret with no leash listed as refused, with the sentence that says how to fix it.
SEC-1. Who may call is in auth-and-roles.md. The workspace, its record and the
reopen are in workspaces-and-sessions.md. The setting names and the
Settings tab are in config.md. Capture's buffers, caps and views are in
capture.md; this file holds what capture masks and when. A flow step's args.secret
is saved and run as saved-flows.md says. Site data is in
site-data.md.
SEC-2. A directory source is one directory per secret and one file per key. The directory's name is the
secret's name and follows names.valid_name. A file's name is the key, and its content, read as
UTF-8 and stripped of surrounding whitespace, is the value.
A hidden entry and a plain file are skipped, and so is an entry whose name is not valid or that resolves outside its directory. A file that cannot be read has no value, and the failure is logged by exception type, never its text.
SEC-3. secrets.dirs lists the directories as PATH does. A name in more than one comes from
the first directory only, and the others add nothing to that secret. A directory that cannot be
listed counts as empty.
SEC-4. A secret's keys are the regular files one level inside its directory, except those whose
names start with . or _. _description is the description and _allowed_urls is the leash. A
bind cannot read a name starting with _.
SEC-5. secrets.entries in the config file overlays the directories. An entry has an optional
description, leash and keys. A name with no directory is a secret only the config defines.
secrets.entries is read from the config file only.
SEC-6. For a name in both sources, the config's description replaces the directory's, and its
allowed_urls replaces the directory's leash entirely, a broken one included. Its keys are added,
and a key with a directory file's name replaces that file for that key only.
SEC-7. A config key is exactly one of {file: <path>}, {env: <NAME>} and {value: <text>},
and anything else stops the boot. A key name cannot be empty or start with _. A file or env
key is read at the moment it is used. A value key is held as a secret string and is never logged,
listed or shown in the Settings tab.
SEC-8. Secrets are on when secrets.dirs or secrets.entries is not empty. With neither set there is
no catalogue: the listing and a bind are refused with a sentence saying so, and every result and
resource is returned as the same object, unscanned. The listing is cached for 30 seconds and holds
no value. Filesystem secrets are visible to every workspace.
SEC-9. A secret's leash is allowed_urls, a list of origins. A secret with no leash is
refused, with no wildcard and no opt-in. A refused secret is not offered to write or a flow, and
is not read for scrubbing.
SEC-10. An origin is scheme, host and port, from urls.scope_origin. The host is lowercased
and an IPv6 host is unbracketed. A port is kept exactly when written, so https://host:443 and
https://host are two origins. Userinfo is never part of one. A URL with no scheme or no host has
no origin.
SEC-11. A leash line is a bare origin. A line with a path, a query, a fragment or credentials is rejected, and so is one that is not a URL. A rejected line is never trimmed into a wider permission. Blank lines are ignored. In a config entry a line that is not a bare origin stops the boot, and the error shows the rebuilt origin, never the line.
SEC-12. A secret is refused when it declares no leash, when its _allowed_urls yields no
origin, and when any line of it is rejected, whether or not the others parse. allowed_urls: [] in
config is declared and allows nowhere, so the secret is refused.
SEC-13. Each listing entry has name, keys, description, allowed_urls, restricted,
origins and key_sources. restricted says whether a leash was declared. origins lists each
source the entry was assembled from. key_sources says where each key is read from, as a path or
an environment variable's name, never a value.
SEC-14. A refused entry carries refused, one sentence that names the source to fix: the
directory's _allowed_urls or the config entry's allowed_urls. A rejected line is listed in
allowed_urls_rejected as its rebuilt origin, with (+ credentials and a path) where something
was dropped, or <a line that is not a URL>. Each refused secret is logged once per process at
WARNING, naming it and the reason.
SEC-15. An entry carries keys_unresolved when a config key's file is missing or its variable
is unset, and inline_keys when a key is a value. A bind of an unresolved key is refused with the
reason.
SEC-16. secret://secrets and GET /secrets return count, workspace and secrets, sorted by name.
The route is behind the server token when one is set. No surface returns a value, and no tool
creates, changes, deletes or gets a single secret.
SEC-17. Only write takes a secret, as secret={"name": ..., "key": ...}. The reference has
those two non-empty strings and nothing else. A bind into any other tool is refused, naming write
as the one that can take one, and upload_file is refused with "not yet".
SEC-18. A write that takes secret may not also give text or url. The secret supplies
text, and navigating first would check the leash against the page being left. Navigation is its
own call.
SEC-19. A bind is refused, before the page is read, when the catalogue is off, the name is
unknown, the key is not in the entry, or the entry is refused. Each refusal is a ValueError and
so a 400. The refusal of a refused entry is also logged at WARNING with the secret's name and key.
SEC-20. The leash is checked against the page the browser is on at the moment of the write, read inside the browser's turn.
- It checks the top page's URL and the origin of the selected frame's document, and both must be allowed. The refusal names the first that is not, and the origins the secret allows.
- A bound write into an element that can host another document (
iframe,frame,object,embed,fencedframe,portal) is refused, since its keys reach a document the leash did not read.
SEC-21. The value is read from the catalogue when it is typed and is not cached, so a rotated credential
is the one typed. secrets.bind is the one function that returns a value, and it returns it to the
caller about to type it. It logs each use at INFO as the name, key, origin and tool.
SEC-22. A bound write does not read the field back, so value is null and text_from says secret. A
write into an input of type=password is never read back, bound or not (ACT-26).
SEC-23. A bound write is a call like any other. It takes the browser's turn, so no call moves the page between the check and the typing, and it is refused while a person holds the browser.
SEC-24. The forms of the typed value are handed to capture before the keystrokes, so a page that echoes it is masked from its first event. If capture cannot take them, the write fails. A failed write keeps its exception's type and status, scrubbed in place, so a dead browser is still a 404.
SEC-25. A flow step binds a secret with args.secret under the same pair rules, worded for saving and
for running. A step that has one gives no text or url and does not name the secret with a
parameter: saving refuses that, so the name and key are written literally. At run time the leash is
checked against the page the step read first. A step's line shows text=[secret:name/key].
SEC-26. A secret is in scope on an origin when its allowed_urls holds that origin. The scrub
looks for the values of every secret in scope, typed or not. Nothing remembers what was typed, so a
restart or a reap loses nothing that matters.
SEC-27. Each workspace's browser has a current origin, held in memory and compared on every
result's URL: a call, a bound write even when its URL is withheld, every flow step, open_session
and a reopen. A top-level arrival on another origin sets it and tells the listeners. A path
change, a repeat and a missing URL tell nothing.
SEC-28. Capture is the second source of origins. Its navigationStarted and
navigationCommitted events, and a navigation's network.beforeRequestSent (a redirect included),
give a context's origin, for any context. A frame's origin is told once per browser and never moves
the top's.
SEC-29. The scrubber is the first listener. On a change it reads the forms of the secrets allowed on the new origin on its own threads, off the event loop, and holds them for that browser. One read serves every caller that needs the same origin.
SEC-30. An opaque page has the origin "": about:blank, data:, javascript: and a file
URL with no host. It is known and has no secret in scope, and nothing is read for it.
chrome-error://chromewebdata/ has an origin of its own and finds nothing allowed there.
SEC-31. Forms are held in process memory for that workspace's browser. They are never written, logged, put in a record or returned. Only forms leave the catalogue, never a bare value.
SEC-32. The catalogue reads values on three paths besides a bind: a browser arriving on an
origin (forms_for), a rotation rebuilding the current origin, and an unknown origin (leashed,
every usable secret). A key that cannot be read adds nothing and is logged by exception type.
SEC-33. The catalogue's revision is a hash of each usable secret's key-file stamps and its
leash, recomputed with the 30-second listing. A stamp is key, inode, modification time and size
from os.stat, which follows a Kubernetes ..data swap. A file config key is stamped the same
way, and an env or value key is fixed for the process's life.
SEC-34. When the revision moves, the next scrub keeps the forms the browser held as kept forms, clears its sets and rebuilds the current origin's. Kept forms mask until the browser ends. Adding an origin to a leash is a rotation.
SEC-35. One browser holds each workspace's slot in the scrubber and in the origins. It takes
a free slot on its first call or is given it by open_session. A reopen that keeps the pages
carries the reaped browser's forms to the new one. A browser that is ended, replaced or not
given the slot is stale.
SEC-36. A stale call is scrubbed with everything the workspace holds and every usable secret,
and installs and builds nothing. An ended browser parks its forms for its workspace until a reopen
claims them, a fresh open_session discards them, or the TTL drops them. A browser ending, by
end_browser or the session.ended event, drops its origin and its forms.
SEC-37. Every result and error of a call on the browser is scrubbed inside the browser's turn, whichever surface carried the call. The scrub first makes sure the sets for the origin before the call and the origin the result's URL names are built. It then uses every set built for this browser, the kept forms included, so the origins the browser left stay masked.
SEC-38. Where the scrub cannot place the page, it uses every usable secret. That is a result
with no URL, an origin with no build done or under way for this browser, a stale browser, and a
selected frame. A build that fails is retried as the every-usable-secret read, and one that fails
twice is ScrubFailed.
SEC-39. A selected frame is unknown. A frame result with in_frame: true makes it so, and a
result with in_frame: false clears it. A browser that took its slot without being opened is
unknown until a result says which.
SEC-40. A call that raises is scrubbed with every usable secret, since its page is unknown.
network_body is scrubbed with every usable secret too, because a body comes from the request's
origin, which the browser may never have been on.
SEC-41. A scrub waits at most 10 seconds for a read. Anything that fails or runs out of time
raises faults.ScrubFailed, a 500, and the call answers a fixed sentence: the result could not be
checked for secrets, so it is not returned, and the action itself may have run. It is raised from
nothing, so neither the failure nor its chain reaches the caller, and the failure is logged by type.
SEC-42. A scrub of a result goes into every string at any depth, in lists, tuples and sets, and into dictionary keys below the top level. A top-level key is a field this code names.
SEC-43. A scrub of an error is in place and keeps its type. It covers args, every string or list of
strings among its attributes, its notes, and its __cause__ and __context__. It then checks
each exception's str(), and one that still carries a value fails the scrub, which becomes
ScrubFailed (SEC-41).
SEC-44. A URL that carries a value is withheld from the record, as a bound write's URL is. It is asked of the raw URL and not by comparison with its scrubbed form. History and a reopen never hold it, and the workspace's clock still slides.
SEC-45. A new browser or a reopen records the page it landed on unless it carries the value of a secret in scope there or one the workspace holds. A check that fails counts as carrying one.
SEC-46. In a flow, a step's result, line, error, landed page and progress line are scrubbed
with the run's typed values and the secrets in scope where the step ran, or every usable secret
when the step raised. A progress line whose scrub fails shows only the tool's name. A step whose
scrub fails stops the run with the fixed sentence, whatever its onError says.
SEC-47. A run keeps every value it has typed for its whole length, so a later step cannot echo one. The run's URL is withheld when the scrubbed page carried one.
SEC-48. A value is looked for in every spelling a page can give back. These forms are made of each value:
- the raw text, with its line breaks dropped, with CR and CRLF made LF, and with each run of whitespace as one space and the ends trimmed;
- percent-encoding with
quoteand withquote_plus; - JSON escapes, with ASCII-only and UTF-8 output,
/as\/, hex in capitals, and Go's\u003cfor<,>and&; - HTML escapes with each quote style a server uses, the browser's attribute serialisation, and
for a no-break space; -
reprof the text, its UTF-8 hex, its reverse and its whole upper case; - base64 in the standard and URL-safe alphabets at the three offsets a value can sit in a longer string, trimmed to the characters that do not depend on a neighbour, a core of at least 6 characters, and the whole padded encoding.
SEC-49. Matching is case-blind for every form except base64, for ASCII letters only. A non-ASCII case variant is not matched, except the value's whole upper case, which is a form of its own. Folding it would change lengths and misalign every later span.
SEC-50. A form shorter than 4 characters is matched only where the characters before and after it are not letters or digits, or the text ends. Otherwise a 3-character value would mask every word that contains it.
SEC-51. A match is replaced by the marker [secret:<name>/<key>]. When two secrets share a
value the marker names both, sorted and joined by |, and never picks one. Overlapping or touching
matches become one span holding every id in it. The marker is the one mask for a catalogued secret
in the scrub, the flow redaction and capture's rows. ••• is what capture shows for what it masks
by header or cookie name.
SEC-52. A match lying wholly inside a marker is left alone when every id in that marker is among the ids being applied, so a value equal to its own key name is not scrubbed twice. A marker with ids not being applied shelters nothing.
SEC-53. A text is scrubbed whole and then cut, and nothing is matched by prefix, because masking the
start of a value at the end of a text would answer a guess one character at a time. A cut never
splits a character, and one that would land inside a marker lands before it. The cuts are
network_body's (CAP-73) and an outline name's, which ends in … (ACT-34); a trailing … a
caller wrote is only text.
SEC-54. For a bound write, the result's text and value fields are null where present. Every
other string in the result is swept of the forms, whatever field it is in.
SEC-55. Every text read of an MCP resource is scrubbed in one middleware, so a client's own
reader, read_resource and show see the same text. A resource read has no before and after, so
it is scrubbed with what the workspace holds and every usable secret.
SEC-56. These resources are not scrubbed, because this server wrote their text: skill://,
ui://, flow://schema and secret://secrets. A read that fails to scrub answers ResourceError
with the fixed sentence, and a refused read has its error scrubbed in place and keeps its type.
SEC-57. JSON text is scrubbed value by value as well as a text, and rewritten and scanned
again when a value changed. A byte content whose media type is JSON, XML, YAML, JavaScript, SVG or
any text/* is scrubbed as UTF-8, with bytes that are not UTF-8 carried through. Other bytes pass.
SEC-58. The REST trees for flows and files scrub their answers as a resource is, and so do delete_flow
and keep_file. A value in a file's name is masked in its listing, signed link
included.
Words a page or a person chose are scrubbed like a resource wherever a call's answer carries them:
a site-data save's report, a live-control summary's visited pages and the saved flows hinted on a
page. workspace://current and the console and network views are scrubbed where they are built, so
their routes are covered too.
SEC-59. The admin API and the admin UI are not scrubbed. They are the operator's view across workspaces. The Console and Network tabs share an agent's read path and show markers.
SEC-60. Capture is wired to the origin source only while secrets are configured. It masks each captured row once, at capture, with the marker, so a row that is tailed or kept is the same masked row. How a context's events wait for the forms of its new origin is CAP-60.
SEC-61. A context that nothing navigated waits on "" after a first attach, and on every usable secret
after a hold again or a lost event, since a navigation may have gone unheard.
SEC-62. A top-level "" is known-empty. A child context whose origin is "", such as
about:blank or srcdoc, inherits what its parent or its opener waits on. One with neither waits
for every usable secret.
SEC-63. See CAP-60 for what a wait drops, and when.
SEC-64. The cookies and authorization tokens capture learns as they pass (CAP-59) are masked with
•••, in the spellings redact.hidden_forms makes: the raw value and its escapes, and not the hex,
reversed or base64 forms a catalogued secret gets.
SEC-65. extract returns html and text, both scrubbed like any result. html is the
element's HTML with the value attribute removed from every input[type=password], template
content included, and from the element itself when it is one. outline never takes a password
input's value as its name. Neither depends on the catalogue or the site.
SEC-66. execute_script runs the script it is given, and what it returns is scrubbed like any
result. screenshot returns pixels, and a result's image is set aside from the scrub and put
back. The tool's description says a field that is not a password field shows its value.
SEC-67. The console and network views read from capture are scrubbed where they are built with
every usable secret and what the workspace holds. network_body is scrubbed as CAP-73 says.
SEC-68. A signed file link serves the file as it is, unscrubbed, a kept text file included.
Its text is read scrubbed through its workspace:// resource.
SEC-69. Pixels are not scrubbed: a screenshot, the live view and a recording show a value in any field that is not a password field. A file in a workspace's folders keeps the bytes it was made with.
SEC-70. What the page itself compares is not scrubbed. outline's text= filter and an XPath
contains() answer a guess as any page script can.
SEC-71. A caller can confirm a guess of a whole value: a result that comes back as a marker tells the caller the guess was right. No guess of a prefix is answered.
SEC-72. execute_script can transform a value in ways no encoding list anticipates, and can
send it away with its own fetch. Once typed, a value is in the page, and anything that reads the
page can read it back. The server keeps it out of what it returns and cannot remove it from the DOM.
SEC-73. The scrub knows only the catalogue's values and capture's learned credentials. A value that no secret allowed on the site holds is not found, whoever typed it. A log line about a secret or a scrub carries a name and key, an origin or an exception's type, never a value or its text.
The action pages are generated from the server's tool schemas, so they describe the version that shipped.
selenium-flow · MIT
Start here
Guides
Lifecycle
Going places
Doing things
Getting things out
Site data
Console and network