Skip to content

feat(app-kit): let a credentialMasks entry mask a whole directory - #36346

Merged
bolichen97 merged 1 commit into
mainfrom
feat/w5-md-notebook-mask-dirs
Nov 14, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
feat/w5-md-notebook-mask-dirs

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

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 residual security.md records). 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

  • Moving Notes' state or changing any built-in's manifest; that is the next PR.
  • Changing what a file entry does.
  • Judging the files inside a declared directory for a second hard link: a declared directory gets what a core HIDDEN directory gets.

What changed (motivation → approach → change)

Goal → approach → change:

  • Grammar (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 in data/, and an entry at or beneath a directory entry is refused (at runtime valid_entries keeps the directory and drops the covered entry). Leaves carry no /; declared_crew_dir_leaves() and declared_crew_dir_leaves_for() list the directory ones. Only the credentialMasks kind takes the form (DeclarationKind.directory_entries): the same engine reads agentReadOnlyDirs, which still refuses a / ending, and agent_readonly_dirs.mask_conflict_errors refuses a read-only directory at or beneath a masked one, since the mask already hides it.
  • Mask in place before the first write (sandbox_staging.py _materialize_declared_mask_dirs, called from the Linux spawn prep in sandbox_argv.py and forwarded by sandbox.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-aside apps/.<name>-data-tmp/ that holds the data while the lifecycle replaces the tree. It never creates apps/<name> or a data directory itself: the lifecycle moves the data aside and back by rename, and a data/ made while it is away would make a keep-data uninstall restore the kept data inside it.
  • No spawn while an app's data has nowhere to be. An app tree on disk with neither data directory refuses the spawn, since that agent would stay unmasked once data/ appears. install_app (apps/manager_install.py) creates data/ 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.
  • Spawn checks (sandbox_aliases.py). A non-directory at a directory entry refuses the spawn; a directory at a file entry still does.
  • The app's own backend (sandbox_tiers.py app_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.
  • Level. APP_SDK_LEVEL becomes 8 in apps/app_sdk_level.py and website/src/app-sdk/sdkLevel.ts, because level 7 already shipped in v0.13.0-rc.1 without this form; scripts/adoption_pin.py reports 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.
  • CI. .github/workflows/ci.yml runs test_app_credential_mask_dirs.py in the namespace-sandbox job, the one runner with user namespaces.
  • Docs. app-kit-platform.md §37 ("Directory entries" and its residuals), §39's cross-check and the level list, security.md, and the App Kit manifest-reference.md and api-reference.md.

Order: builds on #36327 (merged), which stops a sandboxed child renaming apps/<name>/data or 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 agentReadOnlyDirs keeps 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 existing data/, 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 before data/ 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 without data/, and the failed-record one fails while install_app creates data/ 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.py was not collected there because that host's environment lacks httpx.

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_LEVEL constant 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_dir after 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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 13, 2026 03:11
@bolichen97
bolichen97 enabled auto-merge (squash) November 13, 2026 03:11
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/sandbox.py

  • src/kiro_crew/sandbox_aliases.py

  • src/kiro_crew/sandbox_argv.py

  • src/kiro_crew/sandbox_staging.py

  • src/kiro_crew/sandbox_tiers.py

  • @bolichen97 posted a complete reasoning template for 311de8e.

@bolichen97
bolichen97 force-pushed the feat/w5-md-notebook-mask-dirs branch from fa780e6 to fbecf26 Compare November 13, 2026 03:20
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 13, 2026
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 311de8e27eb7e1727ef89091d049489f976fd7d4 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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 APP_SDK_LEVEL from 7 to 8 in website/src/app-sdk/sdkLevel.ts, which nothing displays.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 311de8e27eb7e1727ef89091d049489f976fd7d4 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • A single app with a broken install (tree on disk, no data/) now refuses every sandboxed spawn on the host, not only that app's own agents (_materialize_declared_mask_dirs raises for the whole spawn). Reinstalling clears it and no built-in uses the form yet. Still, think about scoping the refusal to that app's agents, or masking the absent path some other way, before Notes adopts it.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 311de8e27eb7e1727ef89091d049489f976fd7d4 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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 ships

Inventory (10 items) — 10 justified

Intent: 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 md-notebook-staging/ mask. ADDITION.

  1. An app manifest can name a whole directory in credentialMasks ("state/") — justified
  2. Before each Linux spawn, the sandbox creates each absent declared directory in data/ and in the move-aside data directory — justified
  3. A spawn is refused while an app's tree is on disk with no data directory — justified
  4. A spawn is refused when a file or link sits at a declared directory name — justified
  5. The app's own backend gets the declared directory back while it is absent or a real directory — justified
  6. Install creates data/ right after publishing the tree, before the record writes — justified
  7. An agentReadOnlyDirs entry at or beneath a masked directory is refused — justified
  8. App Kit level goes from 7 to 8 (backend and frontend) — justified
  9. The adoption-pin scan reports a directory entry as a level-8 use — justified
  10. The namespace-sandbox CI job runs the new real-sandbox test — justified

[FIRST-PRINCIPLES-REVIEWED] 311de8e

Description read

[DESCRIPTION-READ] e08ba9b456d3334371c7bf47403c76a31977700e8d783fcf1f652801ce3c9ddb

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 311de8e27eb7e1727ef89091d049489f976fd7d4 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 311de8e

Verdict parsed from the review's SHA-scoped output markers for commit 311de8e27eb7e1727ef89091d049489f976fd7d4.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 311de8e27eb7e1727ef89091d049489f976fd7d4 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 311de8e27eb7e1727ef89091d049489f976fd7d4 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 311de8e

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 311de8e27eb7e1727ef89091d049489f976fd7d4 false-positive: <reason, 20 to 500 characters>

@KiroCrewCaptain

KiroCrewCaptain commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: 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 credentialMasks entry of one name ending in / (like "state/") now masks a whole directory, the change is opt-in, and I found no blocking defect. I couldn't run anything, so this rests on reading the code; most CI checks and the AI review lanes for this head were still pending.

Grammar. credential_masks.entry_error only accepts the trailing / for the credentialMasks kind, and agent_readonly_dirs passes its own kind on every call, so "notes/" is still refused there. Overlapping entries are refused when a manifest is validated and dropped at runtime, keeping the directory.

Spawn prep. _materialize_declared_mask_dirs runs before the launcher builds its mounts. It only creates the declared directory, and only inside a data/ or move-aside .<name>-data-tmp/ that is already a real directory. It refuses on a link anywhere in the chain, and it records each directory it sees as a required mask target. So it never creates a data/ that a keep-data uninstall or an update would then move into.

Install change. app_data_dir now runs before the record writes. If it fails, the existing cleanup removes the tree, as before. I

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 311de8e27e · 958 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 4c40ddf
  • What rule changed: a credentialMasks entry of one name ending in / now names a DIRECTORY under the app's own data/, masked whole. Linux spawn prep creates it (and the folders above it) when absent, refusing a link in the chain; the alias pass refuses a non-directory at it; the app's own backend gets it back while it is absent or a real directory. This head also carries fix(sandbox): pin the parents of every hidden crew-home leaf #36327 (parents of every hidden leaf pinned against rename), which this seam relies on.
  • Before -> after (what was allowed/blocked, now): before, such an entry was refused by validation, so nothing was masked for it. After, every other sandboxed process sees the directory empty, including a process started before the backend first wrote into it. Nothing that was masked before is unmasked; no core leaf can be lifted by a declaration (unchanged app_declared_mask_targets filter).
  • Worst case if wrong (breaks commands / leaks secret / locks user out): leaks secret only if the mask failed to cover what an app writes there; refused spawns if a file or link sits at a declared directory's name (the spawn refuses with the path and the fix).
  • Evidence checked (which sandbox result proves it): test/test_app_credential_mask_dirs.py 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 spawn-prep creation the first case fails. Plan tests cover every mode on Linux and the Seatbelt read deny.
  • No regression:
    • Tools still work (which tools/commands were run, result): the namespace tests run a backend that writes by temp and rename inside the lifted directory; md-notebook real-sandbox tests pass.
    • Backward compatible (old config / old data / old callers still work, how checked): grammar only gains a form every earlier build refused; manifests without a directory entry plan, validate and spawn as before (test_app_credential_masks.py, adoption and manifest suites).
    • Existing tests (which suites passed on this head): all test/test_sandbox*.py, the credential-mask, adoption, manifest and SDK-level-mirror suites, test_coverage_omit_contract.py, locally on a host with user namespaces.
  • How to undo: revert this commit; no data is migrated by it, and an app declaring a directory is refused at install again.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 13, 2026
@bolichen97
bolichen97 force-pushed the feat/w5-md-notebook-mask-dirs branch from 4c40ddf to 2cded07 Compare November 13, 2026 06:14
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: spawn prep created the folders above a declared directory
resolution: narrowed to the declared directory inside an existing data/

  • Directory preparation can misplace preserved app data during uninstall span=db12e35c7134

fixed in 2cded07: _materialize_declared_mask_dirs now creates only the declared directory, and only inside an apps/<name>/data that is already a real directory; it never creates apps/<name> or data/, so the keep-data uninstall's shutil.move(tmp_data, data) cannot land inside a data/ a spawn made.
Class swept: the other spawn-prep creator (_materialize_maskable_dirs) makes core leaves directly in the data home; the lifecycle move-backs (uninstall :356, install :418/:827, adopt :139, builtin adoption :365) are safe once prep never creates data/.
Install and update create data/ (app_data_dir), so an installed app's directory is still in place before its backend's first write.
Regression: TestSpawnPrep::test_a_spawn_inside_a_keep_data_uninstall_leaves_the_kept_data_whole runs prep inside the real uninstall right after the tree removal; it and test_without_a_data_dir_nothing_is_created fail on 4c40ddf and pass here.

@bolichen97

bolichen97 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: no

  • Core HIDDEN-leaf parents become rename guards (sandbox_argv.py hidden_leaf_parents) span=12ca3e93ed9f

fixed in 35425a3: the hunk is #36327's commit, and this branch now carries #36327's final head 5b6ebe5 (rebased as eb961a1), which the Opus lane passed on #36327 with no findings.
On that commit a retired leaf (the workspace/md-notebook names) guards its parents only while they exist (os.path.lexists(parent)), so a default install no longer pins workspace/ or workspace/md-notebook; the goldens in test_sandbox_refactor_generated_programs.py drop those six rows.
This PR's own commit still adds no guard: in sandbox_argv.py it adds only the _materialize_declared_mask_dirs import and call.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 2cded07
  • What rule changed: a credentialMasks entry of one name ending in / names a DIRECTORY under the app's own data/, masked whole. Linux spawn prep creates it when absent, only inside an apps/<name>/data that is already a real directory (never apps/<name> or data/ itself, which the app lifecycle moves aside and back), refusing a link in the chain; the alias pass refuses a non-directory at it; the app's own backend gets it back while it is absent or a real directory. This head also carries fix(sandbox): pin the parents of every hidden crew-home leaf #36327's commit (parents of every hidden leaf pinned against rename), rebased onto main.
  • Before -> after (what was allowed/blocked, now): before, such an entry was refused by validation, so nothing was masked for it. After, every other sandboxed process sees the directory empty, including a process started before the backend first wrote into it. Nothing masked before is unmasked; no core leaf can be lifted by a declaration (unchanged app_declared_mask_targets filter).
  • Worst case if wrong (breaks commands / leaks secret / locks user out): leaks a secret only if the mask failed to cover what an app writes there; refused spawns if a file or link sits at a declared directory's name (the refusal names the path and the fix). Spawn prep no longer creates data/, so it cannot make a keep-data uninstall restore the kept data inside a fresh data/.
  • Evidence checked (which sandbox result proves it): test/test_app_credential_mask_dirs.py under the real namespace sandbox (an agent started before the backend writes a temp-then-rename credential still sees the directory empty; a later agent too); TestSpawnPrep::test_a_spawn_inside_a_keep_data_uninstall_leaves_the_kept_data_whole runs spawn prep inside a real keep-data uninstall right after the tree removal and the data comes back whole (it fails on 4c40ddf). A host-side unshare -Urm check confirmed a running namespace's mask follows data/ when the gateway renames it aside and back.
  • No regression:
    • Tools still work (which tools/commands were run, result): the namespace tests run a backend that writes by temp and rename inside the lifted directory; test_app_manager.py install/update/uninstall suites pass.
    • Backward compatible (old config / old data / old callers still work, how checked): the grammar only gains a form every earlier build refused; manifests without a directory entry plan, validate and spawn as before (test_app_credential_masks.py, test_sandbox_governance_mask.py).
    • Existing tests (which suites passed on this head): test_app_credential_mask_dirs.py, test_app_credential_masks.py, test_app_manager.py, test_sandbox_refactor_facade.py, test_sandbox_hidden_leaf_parent_pins.py, test_sandbox_refactor_generated_programs.py, test_sandbox_governance_mask.py (1539 passed), plus flake8, isort, black gate, comment-history, brand, line-cap and docs-lint, locally on a host with user namespaces.
  • How to undo: revert this commit; no data is migrated by it, and an app declaring a directory is refused at install again.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Main is red: Backend Lint & Type Check (3.12) fails mypy at src/kiro_crew/cli_commands_memory.py:335 (bool assigned to list[str]), a semantic conflict between main's #36114 and #36212 that this PR does not touch; reproduced locally on this head. Tracked in #36458, fix open in #36457. This PR rebases onto main once that lands; no override for it.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 13, 2026
@bolichen97
bolichen97 force-pushed the feat/w5-md-notebook-mask-dirs branch from 2cded07 to 35425a3 Compare November 13, 2026 18:12
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased 35425a3 onto main 6c8b798 with #36327's final head (5b6ebe5) as the first commit. The base now carries #36457, so the Backend Lint & Type Check (3.12) mypy red from main (#36458) is gone; mypy src/kiro_crew is clean locally.

Two things main brought that this commit had to adapt to:

  • feat(app-kit): let an app's manifest fence its own dirs from agent writes #33589 moved agentReadOnlyDirs onto the same credential_masks engine. The / form is now gated on DeclarationKind.directory_entries, so only credentialMasks accepts it and agentReadOnlyDirs keeps its grammar. mask_conflict_errors also refuses a read-only directory at or beneath a masked directory.
  • Level 7 already shipped in v0.13.0-rc.1 without directory entries, so this takes level 8 (APP_SDK_LEVEL, sdkLevel.ts, adoption_pin.py, docs).

Local: 4,610 passed / 6 skipped across test/test_sandbox*.py plus the mask, read-only-dir, adoption, manifest, app-manager and SDK suites (the namespace tests ran); flake8, isort, black gate, mypy, comment-history, brand, line-cap, docs-lint and the flake-pattern ratchet are all clean. Semgrep is not installed on this host, so CI's SAST job is the check for that.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 35425a3
  • What rule changed: a credentialMasks entry of one name ending in / names a DIRECTORY under the app's own data/, masked whole. Linux spawn prep creates it when absent, only inside an apps/<name>/data that is already a real directory (never apps/<name> or data/ itself), refusing a link in the chain; the alias pass refuses a non-directory at it; the app's own backend gets it back while it is absent or a real directory. Only the credentialMasks declaration takes the form (DeclarationKind.directory_entries); agentReadOnlyDirs, read by the same engine, keeps its grammar and refuses a read-only directory at or beneath a masked one. This head carries fix(sandbox): pin the parents of every hidden crew-home leaf #36327's final commit (5b6ebe5) first, rebased onto main.
  • Before -> after (what was allowed/blocked, now): before, such an entry was refused by validation, so nothing was masked for it. After, every other sandboxed process sees the directory empty, including a process started before the backend first wrote into it. Nothing masked before is unmasked; no core leaf can be lifted by a declaration (unchanged app_declared_mask_targets filter); no agentReadOnlyDirs seal changes.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): leaks a secret only if the mask failed to cover what an app writes there; refused spawns if a file or link sits at a declared directory's name (the refusal names the path and the fix). Spawn prep never creates data/, so a keep-data uninstall cannot restore the kept data inside a fresh data/.
  • Evidence checked (which sandbox result proves it): test/test_app_credential_mask_dirs.py under the real namespace sandbox on this host (29 passed, none skipped): an agent started before the backend writes a temp-then-rename credential still sees the directory empty, and a later agent too; the keep-data uninstall window test keeps the data whole. test_app_agent_readonly_dirs.py pins the read-only grammar and the new cross-check (fails without the kind gate).
  • No regression:
    • Tools still work (which tools/commands were run, result): the namespace tests run a backend that writes by temp and rename inside the lifted directory; test_app_manager.py install/update/uninstall suites pass.
    • Backward compatible (old config / old data / old callers still work, how checked): the grammar only gains a form every earlier build refused; manifests without a directory entry plan, validate and spawn as before (test_app_credential_masks.py, test_app_agent_readonly_dirs.py, test_sandbox_governance_mask.py).
    • Existing tests (which suites passed on this head): every test/test_sandbox*.py file plus the mask, read-only-dir, adoption, manifest, app-manager, backend-SDK and SDK-level-mirror suites (4,610 passed, 6 skipped), plus flake8, isort, black gate, mypy, comment-history, brand, line-cap, docs-lint and the flake-pattern ratchet, locally on a host with user namespaces.
  • How to undo: revert this commit; no data is migrated by it, and an app declaring a directory is refused at install again.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 13, 2026
bolichen97 added a commit that referenced this pull request Nov 13, 2026
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.
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 14, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Backend Tests (3.12, 3) and Backend Tests (Windows) (3) (and so Coverage Gate) fail at dacf28d on test/test_conductor_agent.py::TestConductorInstaller::test_back_to_back_rounds_keep_a_spend_bound: main's red from #36312 + #37030, tracked in #37243, outside this diff. This PR waits for that fix and rebases onto it; Analyze (python) failed on API rate limit exceeded for installation and is re-run after the window.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 14, 2026
@bolichen97
bolichen97 force-pushed the feat/w5-md-notebook-mask-dirs branch from dacf28d to 40c740e Compare November 14, 2026 15:49
@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 40c740e
  • What rule changed: a credentialMasks entry of one name ending in / names a DIRECTORY under the app's own data directory, masked whole. Linux spawn prep creates it when absent in each data directory the app has (apps/<name>/data/ and the move-aside apps/.<name>-data-tmp/), never creating apps/<name> or a data directory itself, refusing a link in the chain; an app tree on disk with neither data directory refuses the spawn; the alias pass refuses a non-directory at it; the app's own backend gets it back while it is absent or a real directory. Only the credentialMasks declaration takes the form (DeclarationKind.directory_entries); agentReadOnlyDirs keeps its grammar and refuses a read-only directory at or beneath a masked one. This head is one commit on main 671eb71, which carries fix(sandbox): pin the parents of every hidden crew-home leaf #36327 (merged). install_app creates data/ right after publishing the tree, before the record writes.
  • Before -> after (what was allowed/blocked, now): before, such an entry was refused by validation, so nothing was masked for it. After, every other sandboxed process sees the directory empty, including a process started before the backend first wrote into it, and a spawn during an install before data/ exists is refused instead of launching unmasked. Nothing masked before is unmasked; no core leaf can be lifted by a declaration (unchanged app_declared_mask_targets filter); no agentReadOnlyDirs seal changes.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): leaks a secret only if the mask failed to cover what an app writes there; refused spawns if a file or link sits at a declared directory's name, or while an app declaring a directory has its tree but no data directory (the refusal names the app and says to retry or reinstall). Apps that declare no directory entry (every app today) are untouched by both refusals. Spawn prep never creates a data directory, so a keep-data uninstall cannot restore the kept data inside a fresh data/.
  • Evidence checked (which sandbox result proves it): test/test_app_credential_mask_dirs.py under the real namespace sandbox on this host (34 passed, none skipped): an agent started before the backend writes a temp-then-rename credential still sees the directory empty, and a later agent too; prep run inside a real install_app before app_data_dir refuses, inside a real update_app creates the directory in the moved-aside data, and inside a keep-data uninstall keeps the data whole (six of these fail on 35425a3). test_app_agent_readonly_dirs.py pins the read-only grammar and the cross-check.
  • No regression:
    • Tools still work (which tools/commands were run, result): the namespace tests run a backend that writes by temp and rename inside the lifted directory; the app install/update/uninstall suites pass.
    • Backward compatible (old config / old data / old callers still work, how checked): the grammar only gains a form every earlier build refused; manifests without a directory entry plan, validate and spawn as before (test_app_credential_masks.py, test_app_agent_readonly_dirs.py, test_sandbox_governance_mask.py).
    • Existing tests (which suites passed on this head): every test/test_sandbox*.py, test/test_app_*.py, test/test_apps_*.py, credential and md-notebook suite plus test_search_docs.py and the flake-pattern ratchet (12,572 passed, 14 skipped), plus flake8, isort, black gate, mypy, comment-history, brand, line-cap, harness-parity and docs-lint, locally on a host with user namespaces.
  • How to undo: revert this commit; no data is migrated by it, and an app declaring a directory is refused at install again.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased dacf28d onto main 671eb71 to clear the conflict with #36349 (permissions.desktopCapabilities at level 7): the level lists in api-reference.md, app-kit-platform.md, adoption_pin.py and test_builtin_adoption_pins.py now carry both seams; nothing else moved. The conductor red (#37243) is main's and still open; this PR rebases onto its fix when it lands.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 14, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

At 40c740e the GPT, Opus, Design, First Principles and UX lanes pass. The only reds are main's: test/test_conductor_agent.py::TestConductorInstaller::test_back_to_back_rounds_keep_a_spend_bound in Backend Tests (3.12, 3), Backend Tests (Windows) (3), macOS shard 3 and so Coverage Gate (#37243, fixed by #37254, auto-merge armed), plus Analyze (python) on the installation rate limit (re-run). This PR rebases onto #37254 once it merges.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 14, 2026
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.
@bolichen97
bolichen97 force-pushed the feat/w5-md-notebook-mask-dirs branch from 40c740e to 311de8e Compare November 14, 2026 17:22
@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 311de8e
  • What rule changed: a credentialMasks entry of one name ending in / names a DIRECTORY under the app's own data directory, masked whole. Linux spawn prep creates it when absent in each data directory the app has (apps/<name>/data/ and the move-aside apps/.<name>-data-tmp/), never creating apps/<name> or a data directory itself, refusing a link in the chain; an app tree on disk with neither data directory refuses the spawn; the alias pass refuses a non-directory at it; the app's own backend gets it back while it is absent or a real directory. Only the credentialMasks declaration takes the form (DeclarationKind.directory_entries); agentReadOnlyDirs keeps its grammar and refuses a read-only directory at or beneath a masked one. This head is one commit on main 87435b5, which carries fix(sandbox): pin the parents of every hidden crew-home leaf #36327 (merged). install_app creates data/ right after publishing the tree, before the record writes.
  • Before -> after (what was allowed/blocked, now): before, such an entry was refused by validation, so nothing was masked for it. After, every other sandboxed process sees the directory empty, including a process started before the backend first wrote into it, and a spawn during an install before data/ exists is refused instead of launching unmasked. Nothing masked before is unmasked; no core leaf can be lifted by a declaration (unchanged app_declared_mask_targets filter); no agentReadOnlyDirs seal changes.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): leaks a secret only if the mask failed to cover what an app writes there; refused spawns if a file or link sits at a declared directory's name, or while an app declaring a directory has its tree but no data directory (the refusal names the app and says to retry or reinstall). Apps that declare no directory entry (every app today) are untouched by both refusals. Spawn prep never creates a data directory, so a keep-data uninstall cannot restore the kept data inside a fresh data/.
  • Evidence checked (which sandbox result proves it): test/test_app_credential_mask_dirs.py under the real namespace sandbox on this host (34 passed, none skipped): an agent started before the backend writes a temp-then-rename credential still sees the directory empty, and a later agent too; prep run inside a real install_app before app_data_dir refuses, inside a real update_app creates the directory in the moved-aside data, and inside a keep-data uninstall keeps the data whole (six of these fail on 35425a3). test_app_agent_readonly_dirs.py pins the read-only grammar and the cross-check.
  • No regression:
    • Tools still work (which tools/commands were run, result): the namespace tests run a backend that writes by temp and rename inside the lifted directory; the app install/update/uninstall suites pass.
    • Backward compatible (old config / old data / old callers still work, how checked): the grammar only gains a form every earlier build refused; manifests without a directory entry plan, validate and spawn as before (test_app_credential_masks.py, test_app_agent_readonly_dirs.py, test_sandbox_governance_mask.py).
    • Existing tests (which suites passed on this head): every test/test_sandbox*.py, test/test_app_*.py, test/test_apps_*.py, credential and md-notebook suite plus test_search_docs.py and the flake-pattern ratchet (12,572 passed, 14 skipped), plus flake8, isort, black gate, mypy, comment-history, brand, line-cap, harness-parity and docs-lint, locally on a host with user namespaces.
  • How to undo: revert this commit; no data is migrated by it, and an app declaring a directory is refused at install again.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased 40c740e onto main 87435b5, which carries #37254 (the fix for main's conductor red #37243). This PR's commit is unchanged (git range-diff reports =); the old head's in-flight runs were cancelled.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 14, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Head 311de8e is green (PR Readiness passed; GPT, Opus, Design, First Principles and UX pass; all eight macOS shards passed). green_age.py reports main +4 commits since its base 87435b5, overlapping only by directory or import: security.md gained a different paragraph (the ssh-self proxy route from #36839), plus cloud.md, ssh_config_route.py and test_ssh_config_route.py, none of which this diff touches or imports. Checked without a push: this commit cherry-picks cleanly onto main 66dc266, and there the sandbox, credential-mask, read-only-dir, install, app-manager, adoption, SDK-level-mirror, test_ssh_config_route.py and facade-mirror suites pass (4,838 passed, 7 skipped), along with mypy and docs-lint.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Retrospective (round 5, head 311de8e). Every mechanism is kept; nothing is subtracted.

  • Spawn prep creates only the declared directory, and only inside an app data directory that already exists (round 0, db12e35c7134): keep. Removing it reopens the keep-data uninstall defect, where shutil.move lands inside a data/ that spawn prep created. Invariant: spawn prep never creates a directory the lifecycle owns.
  • An app tree with neither data/ nor the move-aside data directory refuses the spawn (round 2, db12e35c7134): keep. Removing it lets an agent start without the declared mask while an install is in flight, which is the goal's own security property. Invariant: a declared directory mask is either in place or the spawn fails closed.
  • install_app creates data/ right after publishing the tree (round 4, 88a7e8644ccc): keep. This is the smaller replacement for skipping trees that have no record, and that skip would reopen db12e35c7134. Removing it would refuse every sandboxed spawn after a failed record write.

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.

bolichen97 added a commit that referenced this pull request Nov 14, 2026
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 KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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_apps writes apps/<name>/app.json without creating data/. So the missing-data refusal at sandbox_staging.py:187 would stop every Linux sandboxed spawn until the backend first creates data/. One fix is to create data/ 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 = 8 for 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_refuses only puts the link at data/. Running it a second time with the link at apps/demo would also pin the "nothing is created through a link" promise there. Separately, sandbox_tiers.py is now 1621 lines, past the 1,600 target, so the declared-mask helpers could move into a sibling module in a follow-up.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants