Repository navigation
feat(app-kit): let a credentialMasks entry mask a whole directory - #36346
Conversation
Sensitive Change ReviewSensitive files changed:
|
fa780e6 to
fbecf26
Compare
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing to check. The diff adds no user-visible control: it changes the backend sandbox and manifest rules, docs and tests, and on the frontend only bumps [UX-REVIEWED] 311de8e Description read[DESCRIPTION-READ] 2fc7f6630d70f539785252d93a4667fc9993c5d4455181437e781039cb3ae640 That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the directory form only applies to manifests that declare it, it raises the SDK level so older hosts refuse such a manifest, and the refusal fails closed. Notes
[DESIGN-REVIEWED] 311de8e Description read[DESCRIPTION-READ] d88294c3d03fc9e53cdcb41babae0bc802c6a205ff292e65580d85f62b651914 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. Every item is opt-in through a manifest. Each traces to the #26967 owner ruling and to AGENTS.md's rule that a capability an app can't get from outside core is an App Kit seam gap, fixed with a generic seam. What this change shipsInventory (10 items) — 10 justifiedIntent: let an app keep a credential it rotates by rename inside a folder that every other sandboxed process sees as empty, so Notes can leave core's hard-coded
[FIRST-PRINCIPLES-REVIEWED] 311de8e Description read[DESCRIPTION-READ] e08ba9b456d3334371c7bf47403c76a31977700e8d783fcf1f652801ce3c9ddb That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Code change approver recommendation: A person should decideWhy: the decider thinks the change is probably fine but estimates a 14% chance that this change introduces a defect, above the 12% limit for approving on its own. Approve. The PR does what it says: a Grammar. Spawn prep. Install change. An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
fbecf26 to
4c40ddf
Compare
Sensitive change review
|
4c40ddf to
2cded07
Compare
|
self-added: yes
|
|
self-added: no
|
Sensitive change review
|
|
Main is red: |
2cded07 to
35425a3
Compare
|
Rebased 35425a3 onto main 6c8b798 with #36327's final head (5b6ebe5) as the first commit. The base now carries #36457, so the Two things main brought that this commit had to adapt to:
Local: 4,610 passed / 6 skipped across |
Sensitive change review
|
Carries #36327 and #36346, which this branch stacks on, as one commit; review them there. #36327: a sandboxed child could rename a parent of a masked crew-home leaf so the next spawn read the leaf at a name no mask covers. Every parent of every hidden spelling now joins the rename guards the read-only seals use (pin_seal_parents on Linux, literal write denies on Seatbelt); a retired leaf guards its parents only while they exist. #36346: an app's credentialMasks entry could only name a file. An entry of one name ending in "/" now names a directory under the app's data dir, masked whole, created before each Linux spawn inside an existing data/, and handed back to the app's own backend while it is absent or a real directory. App Kit level 7.
|
|
dacf28d to
40c740e
Compare
Sensitive change review
|
|
Rebased dacf28d onto main 671eb71 to clear the conflict with #36349 ( |
|
At 40c740e the GPT, Opus, Design, First Principles and UX lanes pass. The only reds are main's: |
An app's credentialMasks entry could only name a file. A writer that stages a temp beside the file and renames it over leaves the temp unmasked while it exists, and the rename detaches the file's mask from every running session. So an app that rewrites a credential by rename had no safe place to keep it. An entry of one name ending in "/" now names a directory under the app's data dir, masked whole. Linux spawn prep creates it when absent in each of the app's existing data directories (data/ and the lifecycle's move-aside spelling, never a data directory itself, which the lifecycle moves aside and back), so the mask is in place before the backend writes into it. An app tree on disk with neither data directory refuses the spawn, so an install in flight cannot leave a new agent without the mask; install_app now creates data/ right after publishing the tree, before any record write that can fail, so a failed install leaves no such tree. A non-directory or a link at the name refuses the spawn too. The app's own backend gets the directory back while it is absent or a real directory. Only the credentialMasks declaration takes the form: the engine's agentReadOnlyDirs still refuses a "/" ending, and refuses a read-only directory at or beneath a masked one. App Kit level 8; an older host's grammar refuses the entry.
40c740e to
311de8e
Compare
Sensitive change review
|
|
Head 311de8e is green ( |
|
Retrospective (round 5, head 311de8e). Every mechanism is kept; nothing is subtracted.
Recurring span 12ca3e93ed9f is closed: #36327 merged as f43dd14, and this branch is now one commit on main with that commit in its base. It no longer carries #36327's diff. |
Carries #36346, which this branch stacks on, as one commit; review it there. An app's credentialMasks entry could only name a file. A writer that stages a temp beside the file and renames it over leaves the temp unmasked while it exists, and the rename detaches the file's mask from every running session. So an app that rewrites a credential by rename had no safe place to keep it. An entry of one name ending in "/" now names a directory under the app's data dir, masked whole. Linux spawn prep creates it when absent in each of the app's existing data directories (data/ and the lifecycle's move-aside spelling, never a data directory itself, which the lifecycle moves aside and back), so the mask is in place before the backend writes into it. An app tree on disk with neither data directory refuses the spawn, so an install in flight cannot leave a new agent without the mask; install_app now creates data/ right after publishing the tree, before any record write that can fail, so a failed install leaves no such tree. A non-directory or a link at the name refuses the spawn too. The app's own backend gets the directory back while it is absent or a real directory. Only the credentialMasks declaration takes the form: the engine's agentReadOnlyDirs still refuses a "/" ending, and refuses a read-only directory at or beneath a masked one. App Kit level 8; an older host's grammar refuses the entry.
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approving. On head 311de8e the review covered:
- the whole source diff and every consumer of the changed functions;
- the new and changed tests: 175 passed, the two credential-mask files passed 5 of 5 repeats under xdist, and the real namespace-sandbox tests ran;
- 17 mutations on the new invariant lines, each of which turned at least one test red;
- the namespace-sandbox and macOS CI jobs on this head, which passed.
What I liked: spawn prep creates only the declared leaf inside a data/ that already exists. It never creates apps/<name> or data/ itself, and there are lifecycle-window tests for mid-install, a failed record write, mid-update and a keep-data uninstall.
Security: this PR adds masking. It does not loosen anything. Only the credentialMasks kind accepts the trailing /, so agentReadOnlyDirs still refuses notes/. The form is limited to one segment under the app's own data directory. The chain is checked with a no-follow link check that fails closed, and the alias pass refuses a non-directory at the leaf. Every hard-link check is guarded by S_ISREG, and _liftable_declared_dir fails closed. An older host refuses such a manifest through its grammar and the SDK level bump. Seatbelt masks the directory as a subpath deny whether or not it exists.
Optional:
- Before a built-in adopts the directory form (the stacked #36365 does this for Notes):
register_builtin_appswritesapps/<name>/app.jsonwithout creatingdata/. So the missing-data refusal atsandbox_staging.py:187would stop every Linux sandboxed spawn until the backend first createsdata/. One fix is to createdata/for an app whose manifest has a directory entry before its app.json is written. - #37218, #36967, #36450 and #32983 also set
APP_SDK_LEVEL = 8for other seams. Whichever merges second has to move to level 9. A one-line merge-order note in the body would help the other authors. test_a_link_in_the_chain_refusesonly puts the link atdata/. Running it a second time with the link atapps/demowould also pin the "nothing is created through a link" promise there. Separately,sandbox_tiers.pyis now 1621 lines, past the 1,600 target, so the declared-mask helpers could move into a sibling module in a follow-up.
Problem / Motivation
Goal: An app can keep a credential it rewrites by rename inside a directory that every other sandboxed process sees as empty, by declaring that directory in its manifest's
credentialMasks.credentialMasks(seam level 3) can only name files. A careful writer stages a temp file beside its target and renames it over, and neither half is safe with a file mask: the temp holds the secret at a name no mask covers while it exists, and a rename over a masked file detaches the mask from every running sandboxed session (the residualsecurity.mdrecords). So an app that keeps a token it can rotate has nowhere safe to put it. Notes (md-notebook) is the case in campaign #26967: core masks its whole state directory,md-notebook-staging/, for exactly this reason, and that hard-coded row is the sandbox exemption standing between Notes and its own repository.Why it matters
The owner ruling in #26967 (comment) (item 5) asks for Notes to run inside the standard sandbox before anything else. Its GitHub token, vault registry and sync settings can move into its own data folder only if a whole folder can be masked there, with the same protection core gives
md-notebook-staging/today. The seam is generic, so any app with a rotating credential gets the same.Not a goal
HIDDENdirectory gets.What changed (motivation → approach → change)
Goal → approach → change:
apps/credential_masks.py). An entry of one name ending in/("state/") names a directory. Deeper ones (a/b/) are refused, so the directory always sits directly indata/, and an entry at or beneath a directory entry is refused (at runtimevalid_entrieskeeps the directory and drops the covered entry). Leaves carry no/;declared_crew_dir_leaves()anddeclared_crew_dir_leaves_for()list the directory ones. Only thecredentialMaskskind takes the form (DeclarationKind.directory_entries): the same engine readsagentReadOnlyDirs, which still refuses a/ending, andagent_readonly_dirs.mask_conflict_errorsrefuses a read-only directory at or beneath a masked one, since the mask already hides it.sandbox_staging.py_materialize_declared_mask_dirs, called from the Linux spawn prep insandbox_argv.pyand forwarded bysandbox.py). The namespace launcher skips an absent directory, so a directory the backend created after an agent spawned would be in that agent's view. Prep creates each absent declared directory (0700) in every data directory the app has:data/, and the move-asideapps/.<name>-data-tmp/that holds the data while the lifecycle replaces the tree. It never createsapps/<name>or a data directory itself: the lifecycle moves the data aside and back by rename, and adata/made while it is away would make a keep-data uninstall restore the kept data inside it.data/appears.install_app(apps/manager_install.py) createsdata/right after publishing the tree, before any record write that can fail, so only an install killed in that instant leaves such a tree; installing again clears it. Prep also refuses a link anywhere in the chain and notes every directory it saw as a required mask target. Seatbelt needs nothing: its denies hold for absent names.sandbox_aliases.py). A non-directory at a directory entry refuses the spawn; a directory at a file entry still does.sandbox_tiers.pyapp_declared_mask_targets) gets a directory entry back while it is absent or a real directory (_liftable_declared_dir), judged from the same manifest source it already reads.APP_SDK_LEVELbecomes 8 inapps/app_sdk_level.pyandwebsite/src/app-sdk/sdkLevel.ts, because level 7 already shipped in v0.13.0-rc.1 without this form;scripts/adoption_pin.pyreports a directory entry as a level-8 use. An older host's grammar refuses the/ending, so it refuses to install such a manifest instead of running the app with the folder unmasked..github/workflows/ci.ymlrunstest_app_credential_mask_dirs.pyin the namespace-sandbox job, the one runner with user namespaces.app-kit-platform.md§37 ("Directory entries" and its residuals), §39's cross-check and the level list,security.md, and the App Kitmanifest-reference.mdandapi-reference.md.Order: builds on #36327 (merged), which stops a sandboxed child renaming
apps/<name>/dataor the folders above it, so a declared directory cannot be carried out from under its mask.Backwards compatibility
Compatible: the grammar only gains a form every earlier build refused, so no manifest that installs today changes meaning, and an app without a directory entry plans, validates and spawns as before.
Removes nothing: no table row, refusal or key goes; the new refusals (a non-directory at a declared directory, a read-only directory at or beneath one) apply only to a manifest carrying a directory entry, and
agentReadOnlyDirskeeps its grammar.Tests
test/test_app_credential_mask_dirs.py(new): the grammar (accepted and refused shapes, overlaps refused and dropped, both spellings listed); the plan masks the directory in every mode on Linux and denies reads under it on Seatbelt; spawn prep creates an absent directory inside an existingdata/, in the move-aside spelling while the data is there, and in both when both exist; it keeps an existing one, refuses an app tree whose data directory is missing or is a file, skips an app with nothing on disk, refuses a linked chain; a spawn inside a real install beforedata/exists refuses, an install whose record write fails leaves spawns working, a spawn inside a real update creates the directory in the moved-aside data and it comes back with it, and a spawn between a keep-data uninstall's tree removal and its restore leaves the kept data whole. Six of these fail on a prep that skipped an app withoutdata/, and the failed-record one fails whileinstall_appcreatesdata/after the record; the alias pass refuses a file or a link at a directory entry and still refuses a directory at a file entry; the backend gets an absent or real directory back and nothing else. Under the real namespace sandbox: an agent started BEFORE the backend writes a temp-then-rename credential into the directory still sees it empty, and a later agent sees it empty too. Without the prep call the first one fails.test/test_app_credential_masks.py:"dir/"moves from the refused list to the accepted one;"a/b/"and"dir//"are refused.test/test_app_agent_readonly_dirs.py: a read-only directory at or beneath a masked directory refuses the manifest, and"notes/"is still refused there; both fail without the kind check.test/test_builtin_adoption_pins.py: a directory entry is reported as a level-8 use.test/test_sandbox_refactor_facade.py: the two new owner names are forwarded.Determinism: the spawn-prep tests that drive the install, update and uninstall windows and the missing-
data/cases passed 20 of 20 repeats, and the whole file passed in three shuffled orders (35 tests each).All
test/test_sandbox*.py,test/test_app_*.py,test/test_apps_*.py, credential and md-notebook suites pass locally (15,347 passed, 18 skipped,-n 8 --dist loadgroup, with the install, registry, desktop and facade-mirror suites) on a host with user namespaces, where the namespace tests run;test_apps_market_client.pywas not collected there because that host's environment lackshttpx.Manual verification
N/A: the namespace tests above drive the real Linux sandbox. With no macOS host here, the Seatbelt half is checked on the rendered profile, and
macOS Tests (on demand)runs the backend suite on macos-15 for this head, since the diff touches the sandbox files on its path list.Screenshots / video
Why no screenshot: the only frontend change is the
APP_SDK_LEVELconstant an app bundle reads; nothing on screen changes.Related Issues
Part of #26967
Sibling sweep
Siblings: none -- this PR adds one materializer for declared directories, and the only other spawn-prep creator,
_materialize_maskable_dirs, makes core leaves that sit directly in the data home, none of which the app lifecycle moves aside and back. The lifecycle windows it must cover are the three that move or create an app's data: install (app_data_dirafter the tree), update, and keep-data uninstall; each has a test above.Pattern harvest
Not generalizable: the one spawn-prep step that made folders inside an app's tree now creates only the declared directory, inside a
data/the gateway already made.Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)