Skip to content

secrets and scope

Dr K edited this page Nov 14, 2026 · 3 revisions

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.

Use cases

  • An operator mounts a Kubernetes Secret and adds one _allowed_urls file. An agent signs in with write(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 to write.
  • A person types a catalogued password in the live view, and a later extract of 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.

Neighbours

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.

Where secrets come from

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.

Where a secret may be used

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.

Typing a 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].

The secrets in scope

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.

What a result is scrubbed with

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.

The spellings and the marker

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 quote and with quote_plus;
  • JSON escapes, with ASCII-only and UTF-8 output, / as \/, hex in capitals, and Go's \u003c for <, > and &;
  • HTML escapes with each quote style a server uses, the browser's attribute serialisation, and &nbsp; for a no-break space;
  • repr of 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.

Resources and routes

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.

Capture

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.

What each action does with a secret in scope

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.

Not scrubbed, and the limits that stand

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.

Clone this wiki locally