Files
reverse-engineering-anything/docs/specs/desktop-app-environments/build-secrets/spec.md
T
387bcb795d feat(desktop): isolate declared secrets during app builds (#9225)
* fix(desktop): preserve local file URL authority

* fix(desktop): preserve local file URL authority

* fix(desktop): preserve local file URL authority

* fix(desktop): render captured file URLs at launch

* fix(desktop): classify numeric timestamps using field context

* fix(desktop): classify numeric timestamps using field context

* fix(desktop): classify numeric timestamps using field context

* fix(desktop): retain context for generated draft values

* fix(desktop): retain context for generated draft values

* fix(desktop): retain context for generated draft values

* test(desktop): cover generated IDs in text guards

* test(desktop): cover generated IDs in text guards

* test(desktop): cover generated IDs in text guards

* fix(desktop): isolate launcher URL encoding

* fix(desktop): isolate launcher URL encoding

* fix(desktop): isolate launcher URL encoding

* fix(desktop): isolate launcher URL encoding

* fix(desktop): bound private key redaction spans

* fix(desktop): retain published bundle on copy failure

* fix(desktop): retain secret file cleanup owners

* fix(desktop): retain both published output cleanup owners

* test(desktop): verify UTF-16 credential refusal

* test(desktop): verify truncated secret redaction over MCP

* fix(desktop): retain clean text in noisy record fields

* fix(desktop): classify added line values in one pass

* fix(desktop): scan private key runs in one pass

* fix(desktop): apply XML quote rules to text drafts

* fix(desktop): distinguish XML attributes from quoted text

* fix(desktop): preserve parsed XML line context

* Format appTaskChecks.ts with the pinned oxfmt

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): retain partial XML syntax facts

* fix(desktop): recognize markdown autolinks in drafts

* fix(desktop): reuse export exclusions in task drafts

* fix(desktop): report unchecked client build paths

* docs(desktop): clarify gzip scrub limits

* test(desktop): build the fixture JWT from its parts and reformat

The literal token made every edit of this file trip secret scanners; the test
checks the same string. Also applies the pinned oxfmt to the key-run test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): reuse export exclusions in task drafts

* docs(desktop): clarify gzip scrub limits

* fix(setup): own desktop build process cleanup

* fix(desktop): find no private key in NSS's key4.db password check

An Electron app's NSS key database holds a password-check value shaped like
an encrypted private key, so every such export was refused. An encrypted key
now counts only under a password-based encryption scheme, never PBKDF2 or
PBMAC1, and with at least the 48 bytes of encrypted data the smallest key
needs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(doctor): compare desktop settings with resolved defaults

* style(desktop): format the noisy-record draft files with the pinned oxfmt

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(desktop): give the root-array draft test its own describe

The records describe grew past the 150-line lint limit with it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(doctor): inspect client-recorded desktop runners

* fix(doctor): reuse matching runner probes

* fix(setup): propagate cancellation to desktop actions

* fix(setup): stop Hopper on cancel, never report a cancelled setup ready, and keep a failed action's client setting

- The Hopper install gets setup's signal: Linux already honoured it, and the
  macOS installer now stops its downloads and stops before mounting or copying.
- runSetup checks the signal after the final doctor and close, so a
  cancellation there raises instead of returning ready.
- A failed pack or agentenv install no longer writes its archive or runner to
  client configs, so the setting the client already had stays.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): close five withheld-state gaps a review found

- A sign-in window whose walk hit its entry limit, could not read a path or
  left a change unconfirmed is refused, rather than trusted as complete.
- The export refuses app dconf keys the sign-in window changed and the seed
  would ship with a different value, naming the keys, not their values.
- A bundle holding a gzip file that expands past what REA scans is refused.
- Withheld bytes are kept under a handle of their own, created exclusively and
  never replaced; a later build's different bytes take the next free handle,
  and a handle the computer's answer names is checked before any write.
- Setting names a Python keyword or a leading digit would break get file_,
  and names that collide get _2, _3 in a stable order.
- Adds the feature's tasks.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): redact a cut secret's start only at REA's own cuts

The boundary match for a secret cut short hid the start of any ellipsis-ended
text, so "Please…" became a redaction. It now applies only where text ends
one of REA's value cuts, whose lengths the producers and the redactor share,
and the host redacts the app's stderr and progress before it quotes their
end. Redacting before anything cuts stays a follow-up.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(setup): keep the completed setup result in a cancellation after cleanup

A cancellation during the final doctor or host close carried only the applied
actions, dropping each client's result and backup path and the doctor report.
It now carries the whole result as setup_result, as doctor's cancellation
carries its report.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(desktop): publish secret files atomically, decompress a gzip seed once, and scan JSON strings linearly

- A secret file is written under a private temporary name and linked to its
  handle, so a concurrent export never reads a half-written file and reuses
  its handle for other bytes.
- The export decompresses each gzip seed file once and shares the result
  with the secret scan, the credential scan and the size refusal.
- The cut-secret stopgap finds JSON string literals in one forward pass
  instead of restarting at every quote.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(desktop): move launch execution to boundary suite

* fix(desktop): redact build schema failure output

* refactor(desktop): normalize schema failure once

* fix(desktop): omit unsafe schema parser snippets

* fix(desktop): preserve draft change and selected path evidence

* test(desktop): group retained dconf note regressions

* fix(desktop): respect archive entry format in draft checks

* test(desktop): separate unowned-file draft note cases

* fix(desktop): preserve explicitly selected journal documents

* fix(xml): avoid scanning selected ancestors per tag

* fix(desktop): exclude covered text runs from draft counts

* fix: preserve text when drafting desktop checks

* fix: restore nested desktop state aliases

* refactor: share UUID recognition across draft checks

* fix: retain multiline XML attribute context

* fix: retain relationship identifiers in task drafts

* docs: clarify desktop draft identifier handling

* test(desktop): type formatting run cases as pairs

* fix(desktop): carry document format into selector evaluation

* test(desktop): separate markup boundary regression group

* fix(desktop): propagate formats through draft selectors

* fix(desktop): switch selector format within archive entries

* test(desktop): remove duplicate seed filename case

* fix(setup): retain diagnostics when cancellation overlaps failure

* refactor(setup): keep command cancellation at its owner

* test(setup): verify cancellation at the application boundary

* test(desktop): pass JSON format in exported index parity

* docs(desktop): clarify task checks before scratch export

* fix(desktop): respell selected paths in file URLs

* test(desktop): group captured document spelling cases

* fix(desktop): retain temporary secret file cleanup

* fix(desktop): preserve unmarked token-shaped values

* fix(desktop): withhold drafts after secret use

* fix(desktop): guard drafts against shared secret changes

* test(desktop): compare preserved seed bytes without enumeration

* fix(desktop): bound draft preview serialization

* fix(desktop): restore selected state aliases

* fix(desktop): respect entry format in draft noise

* test(desktop): match exported alias evidence at its JSON boundary

* fix(desktop): retain app state logs in exported seeds

* fix: align desktop numeric seed comparisons

* test(desktop): keep one draft exclusion fixture import

* test(desktop): retain log eligibility across draft test groups

* fix(doctor): resolve empty registered desktop runner

* style: fix desktop launch test formatting

* style: format native command path schema

* fix(desktop): map selected external launch paths

* style(desktop): format seed document regressions

* test(desktop): group launch URL regressions

* fix(desktop): omit redundant nested state aliases

* fix(desktop): compare added free text as a whole

* fix(desktop): check recompressed seeds as shipped

* docs(desktop): clarify recovered seed format

* test(desktop): group shipped gzip seed checks

* fix: retain quoted identifier text in task drafts

* fix: recognize Unicode XML in desktop state readers

* fix(desktop): bound nested draft checks

* fix(desktop): explain missing arrays in truncated views

* fix(desktop): find XML type references in archives

* test(desktop): remove duplicated capture assertions

* fix(desktop): retain nested omitted text boundaries

* style(desktop): format draft value imports

* test(desktop): group model and draft value checks

* fix(desktop): map captured launch paths once

* refactor: remove unused whole-text guard state

* refactor: stop passing unused text children

* test: align free-text checks with whole-note policy

* fix: validate recompressed desktop archive seeds

* style(desktop): format archive seed regression

* fix(desktop): retain placed-item sibling guards

* fix(desktop): preserve archive paths and bound doctor reads

* fix(doctor): refuse non-files before descriptor admission

* fix(setup): track remaining cleanup resources across retries

* test(desktop): specify XML format in heap pairing fixture

* fix(doctor): query agentenv for model endpoint

* fix(doctor): preserve uncertainty for empty endpoint override

* fix(desktop): protect host controls and quote withheld paths

* fix: redact declared form-encoded secrets

* fix(desktop): redact runtime schema errors

* fix(desktop): normalize captured file URLs

* fix(desktop): report seeded files by capture path

* fix(desktop): retain startup readiness failure stage

* fix(desktop): retain JSON date checks

* fix(desktop): preserve archive formatting checks

* fix(desktop): preserve explicitly selected journal files

* fix(desktop): report build command transport limits

* docs(desktop): clarify unreadable dconf versions

* test(desktop): remove duplicate history regression

* fix(desktop): align XML names with exported reader

* fix(desktop): create selected state alias targets

* fix(desktop): inspect supported runtime archives

* fix(desktop): retain record identity in draft checks

* fix(desktop): refuse unchecked declared secrets

* fix(desktop): retain partial withheld export receipts

* fix(desktop): detect escaped secrets in JSON state

* fix(desktop): scrub XML independently of reader compatibility

* fix(desktop): preserve file aliases and reader diagnostics

* fix(desktop): scan escaped secrets in UTF-16 JSON

* style(desktop): format secret scan changes

* style(desktop): format review fixes

* style(desktop): format capture review fixes

* style(desktop): format review changes

---------

Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 23:23:13 +08:00

6.9 KiB

Secrets typed unseen

Outcome

An agent building an environment for an app that asks for a password, a licence key or a sign-in types it through REA without seeing it. The person keeps the secret in a file on the build host; the agent names it by a handle; REA types its value into the build computer. No tool result, action log, witness record or exported bundle holds the value, and an export refuses a bundle that does. The sign-in or licence state the app writes is withheld from the bundle and supplied by whoever runs it, unless the person consents to seed it. REA does not infer secrecy from a value or name.

Requirements

  • Secret files: one per handle, in $XDG_CONFIG_HOME/rea/build-secrets/, or ~/.config/rea/build-secrets/ when XDG_CONFIG_HOME is unset or relative, as the REA server's environment gives them. A handle is ^[a-z0-9][a-z0-9._-]{0,62}$. REA reads a handle's file when it types it and refuses it unless the folder is a real folder, not a symbolic link, and the file is a regular file, opened without following a link and without blocking, owned by the server's user, with no group or other permission bit, of at most one secret's size, and UTF-8. Its text, without one final \n or \r\n, must hold 8 to 1024 characters and no control character. A refusal names the file and the reason, never its text.
  • act_on_build_computer action type_secret, taking only secret, a handle, and refusing screenshot, text or any other field, and its absence: REA sends computer_type with the value as text. Its result is REA's own: summary Typed the secret <handle> and the driver's applied, delivery and others_since_frame, one text block saying the same, and no image. A driver refusal, or a call that fails, is REA's own error naming the handle, without the driver's words or the cause, since either could quote the value; a cancelled call stays a cancellation.
  • Action log: a type_secret entry records {"secret": "<handle>"} and counts as an input for the witness's edit and near miss, as type does. Every string the log keeps, member names included, has each secret typed on the server replaced by <secret:<handle>>.
  • Results and records: every string in each build tool's text content and structured content, errors included, and in witness.json's record, has each secret typed on the server, in each text spelling below, replaced by <secret:<handle>>. Images pass as they are. After this server uses a declared secret, automatic task drafting is withheld before it runs; the capture remains available for a manually written task and export. Check descriptions redact complete known values before shortening them. Ordinary text is never redacted merely because it resembles part of a secret. The host redacts the app's stderr and capture progress before quoting their end.
  • Export scan: before writing a bundle on the host, REA searches each file's path and bytes for every secret typed on the server and every other one the folder holds, whatever its permissions, in these spellings: as it is, escaped in JSON, UTF-16LE and UTF-16BE, lower- and upper-case hex of its UTF-8, base64 in either alphabet of the characters that depend on the value alone at each of the three byte alignments, and URL-encoded with upper- or lower-case escapes and with + for a space; and the same inside a gzip file, decompressed up to 64 MiB. A bundle holding one is refused as an invalid request naming each secret's handle and the files, each value in a file's name shown as <secret:<handle>>, and nothing is written to the folder. A gzip file that expands past 64 MiB, which the scan cannot see inside, is refused by name when known secrets are checked.
  • The skill asks the person for a secret's file instead of the secret, types it only into a masked field, and stops when an export finds a secret.
  • Withheld state: files under the owned paths that changed after checkpoint pre-sign-in up to post-sign-in, by the capture's recorded changes, and those withhold names, are withheld. With only one of the two checkpoints the export is refused, and so is a window in which a walk, from pre-sign-in to post-sign-in, stopped at its entry limit, could not list a directory or check a path, or left a change unconfirmed, since it may have missed a file the sign-in wrote. The draft leaves the withheld files out and lists them as withheld_files; a task check naming one is refused. An export is refused, too, for a dconf key of the app that the window changed and the seed holds other than before it, since the class seeds dconf keys and cannot withhold them, unless the withheld state is seeded with consent. Each withheld file present at the seed is left out of it and becomes a SecretStr field of the class's Settings, named as Python takes an argument and distinct within the app, which env.toml's [settings] sets to env:REA_<APP>_<FILE>, so a deploy without the variable is refused with its name. At first boot, before keep_initial, the class writes each from its setting, the file's bytes in base64, mode 0600; data/get serves it neither as a part nor in the views, and data/reset restores it. The README names each variable and how to fill it. A file larger than 48 KiB is refused. The CLI copies the withheld files to --withheld-copy, outside the bundle, and the build host keeps each one's base64 as the secret rea-<app>-<file>, or the first rea-<app>-<file>-<n> holding no other value (0600), never replacing a secret file, named in the export's withheld_files.
  • The export refuses a seed file whose bytes equal a withheld file's, by SHA-256, naming both files; a backup that differs from the withheld file is not caught, so the agent trashes backups before seed.
  • Witness: start_build_computer from a bundle takes settings, each REA_* variable mapped to a handle, whose value, up to 64 Ki characters, REA puts in the deploy's environment only.
  • Consent: record_build_consent keeps the person's words, kind licence or seed_sign_in, with the computer, source: "relayed". The export writes every consent into the bundle's consent.json. seed_sign_in: true seeds the withheld files instead, refused unless a seed_sign_in consent was recorded; the CLI refuses --seed-withheld without one in --consent.

Non-goals

  • Redacting images: screenshots and the witness's recording show whatever the screen shows, so a secret stays unseen only in a field that masks it.
  • Finding a value inside a zip archive's compressed entries, or a token an app derives from a secret, such as a session token after a sign-in.
  • Keeping the secrets folder from the building agent's own shell on the same host; the client's permission rules do that.
  • Asking the person through the client itself: the agent relays their words, so a consent is only as true as the agent's relay.
  • Withholding state outside the owned paths, which the bundle never seeds.