feat(host/plugins): grant each folder a files pattern names #2249

Merged
enricobuehler merged 2 commits from feat/plugin-folder-files-patterns into main 2026-11-01 00:49:28 +00:00
Owner

Why

Every declared reads root is tree-walked at converge, not only a grant: eight catalog plugins declare game trees or multi-thousand-file trees, wants asked for whole game folders (one walk per yes), and a junction's ACE landed on its target while the sandboxed runner was refused at the link. The reporter's closed Steam root with a junctioned steamapps read 0 entries with no prompt and allowed but not visible in the runner log.

What

  • Junction (0dd527a7e): each reparse point on the way to a root is a root of its own. Ace::Link is (RX) without inheritance, placed, read back and removed through a handle opened with FILE_FLAG_OPEN_REPARSE_POINT (SetKernelObjectSecurity / GetSecurityInfo): never followed, never walked, never TreeSetNamedSecurityInfoW. link_of works on Windows (a drive prefix is plain). A pending row keeps the spelling the plugin asked with, so an allow records the link; a request that records one converges at once rather than at the next minute. Console and CLI show the spelled path.
  • Files patterns (5ace4e57e): a path with one * component names each folder under its base (EA Games/*/__Installer, XboxGames/*/Content, GOG Games/*). The host judges it by its base, binds the base and each match by their own files, re-expands at every converge, and opens a concrete ask that a files root or pattern already covers before it answers granted. A * path is a files pattern whatever flag came with it: a plugin on a kit that predates files asks with a plain string.
  • Docs: the manifest table and the wants paragraph in writing-plugins; the kit's AccessRequestPath.files comment.

Measurements, VM 9101, host from this branch, a real second disk E:

Case Result
Closed root (by SID), steamapps junctioned to E:\SteamLib, link ACE stripped 0 entries, allowed but not visible; the minute's verify logs runner ACE had gone, placed again on the junction; runner restart → 4 entries. (RX) on the link object alone, files ACE on the target, record kind link
GOG, record with EXE / without lists with no prompt and no folder ACE / pends its folder by files, allowed in 984 ms, (OI)(NP)(RX) on that folder alone
EA E:\EA Games\*\__Installer one prompt, allowed in 939 ms, ACEs on the base and __Installer; 300 files under Data untouched
Xbox E:\XboxGames\*\Content + root two prompts, 1.2 s each; Halo\Content and the root only; pak files untouched
Xbox WindowsApps/* replacing the tree ACE one conversion of 26 s (revoking the old tree ACE), then 203 files roots; AppxManifest.xml readable, a file one level down carries nothing of ours; WindowsApps\Projected refuses WRITE_DAC to SYSTEM, logged once
.133, real mklink /J a_link_ace_lands_on_the_link_not_its_target, a_path_through_a_junction_keeps_its_spelling_and_binds_the_link and the two existing ACL tests pass

Local: 66 host tests on the Mac, xwin clippy on both Windows lanes, census 63 unchanged, hygiene, writing, docs-drift, gitleaks; OpenAPI, its docs-site copy and sdk/src/gen regenerated.

Rejected

  • A SYSTEM file-read broker: the kit's read API is synchronous on both lines, a SYSTEM read service needs its own review, and watchDirs would stop working. Deferred until a box with a Game Pass title shows whether SYSTEM can ACE a locked Content.
  • Dropping WindowsApps from the xbox manifest: a package folder grants Users and its own capability only, no ALL APPLICATION PACKAGES, so the plugin cannot read AppxManifest.xml without an ACE. WindowsApps/* is the bounded form.

Not verified

  • The Windows run of the host test suite has 11 failures that main's own files also have (Unix paths, plugin write roots Windows refuses by rule); CI never runs the host suite on Windows.
  • A pattern on a Linux host (it expands to binds) ran only in unit tests.
  • A one-time walk remains on upgrade for a plugin that moves a tree root to a pattern: the old inherited ACEs come off. The console shows it as a walk.
  • The ten plugin releases follow in their repos; Epic through its own branch.
## Why Every declared `reads` root is tree-walked at converge, not only a grant: eight catalog plugins declare game trees or multi-thousand-file trees, `wants` asked for whole game folders (one walk per yes), and a junction's ACE landed on its target while the sandboxed runner was refused at the link. The reporter's closed Steam root with a junctioned `steamapps` read 0 entries with no prompt and `allowed but not visible` in the runner log. ## What - **Junction** (`0dd527a7e`): each reparse point on the way to a root is a root of its own. `Ace::Link` is `(RX)` without inheritance, placed, read back and removed through a handle opened with `FILE_FLAG_OPEN_REPARSE_POINT` (`SetKernelObjectSecurity` / `GetSecurityInfo`): never followed, never walked, never `TreeSetNamedSecurityInfoW`. `link_of` works on Windows (a drive prefix is plain). A pending row keeps the spelling the plugin asked with, so an allow records the link; a request that records one converges at once rather than at the next minute. Console and CLI show the spelled path. - **Files patterns** (`5ace4e57e`): a path with one `*` component names each folder under its base (`EA Games/*/__Installer`, `XboxGames/*/Content`, `GOG Games/*`). The host judges it by its base, binds the base and each match by their own files, re-expands at every converge, and opens a concrete ask that a files root or pattern already covers before it answers `granted`. A `*` path is a files pattern whatever flag came with it: a plugin on a kit that predates `files` asks with a plain string. - Docs: the manifest table and the `wants` paragraph in writing-plugins; the kit's `AccessRequestPath.files` comment. ## Measurements, VM 9101, host from this branch, a real second disk `E:` | Case | Result | |---|---| | Closed root (by SID), `steamapps` junctioned to `E:\SteamLib`, link ACE stripped | 0 entries, `allowed but not visible`; the minute's verify logs `runner ACE had gone, placed again` on the junction; runner restart → 4 entries. `(RX)` on the link object alone, files ACE on the target, record kind `link` | | GOG, record with `EXE` / without | lists with no prompt and no folder ACE / pends its folder by files, allowed in 984 ms, `(OI)(NP)(RX)` on that folder alone | | EA `E:\EA Games\*\__Installer` | one prompt, allowed in 939 ms, ACEs on the base and `__Installer`; 300 files under `Data` untouched | | Xbox `E:\XboxGames\*\Content` + root | two prompts, 1.2 s each; `Halo\Content` and the root only; pak files untouched | | Xbox `WindowsApps/*` replacing the tree ACE | one conversion of 26 s (revoking the old tree ACE), then 203 files roots; `AppxManifest.xml` readable, a file one level down carries nothing of ours; `WindowsApps\Projected` refuses WRITE_DAC to SYSTEM, logged once | | `.133`, real `mklink /J` | `a_link_ace_lands_on_the_link_not_its_target`, `a_path_through_a_junction_keeps_its_spelling_and_binds_the_link` and the two existing ACL tests pass | Local: 66 host tests on the Mac, xwin clippy on both Windows lanes, census 63 unchanged, hygiene, writing, docs-drift, gitleaks; OpenAPI, its docs-site copy and `sdk/src/gen` regenerated. ## Rejected - A SYSTEM file-read broker: the kit's read API is synchronous on both lines, a SYSTEM read service needs its own review, and `watchDirs` would stop working. Deferred until a box with a Game Pass title shows whether SYSTEM can ACE a locked `Content`. - Dropping `WindowsApps` from the xbox manifest: a package folder grants `Users` and its own capability only, no `ALL APPLICATION PACKAGES`, so the plugin cannot read `AppxManifest.xml` without an ACE. `WindowsApps/*` is the bounded form. ## Not verified - The Windows run of the host test suite has 11 failures that main's own files also have (Unix paths, plugin write roots Windows refuses by rule); CI never runs the host suite on Windows. - A pattern on a Linux host (it expands to binds) ran only in unit tests. - A one-time walk remains on upgrade for a plugin that moves a tree root to a pattern: the old inherited ACEs come off. The console shows it as a walk. - The ten plugin releases follow in their repos; Epic through its own branch.
enricobuehler added 2 commits 2026-11-01 00:23:01 +00:00
A sandboxed runner opens a root through the path the plugin spells. When
that path is a junction the ACE lands on the target, because a DACL set by
name follows the link, and the container is refused at the link itself. A
closed Steam root with `steamapps` junctioned elsewhere read 0 entries with
no prompt: the host answered `granted` from the canonical path.

Each reparse point on the way to a root is now a root of its own, with a
read ACE placed, read back and removed through a handle opened on the link,
never followed and never walked. A request keeps the spelling it was asked
with, so an allow records the link, and a request that records one
converges at once instead of at the next minute.

A pending row shows the spelled path in the console and the CLI.
feat(host/plugins): grant each folder a files pattern names
windows-host / package (arm64, 2d57a0eec0cb44d95c918c3f9734f60455a1306ae5085d76fc68f44e3ee30d09, bun-windows-aarch64.zip, , --no-default-features --features gamestream, -C target-feature=+crt-static -C link-arg=/INCLUDE:lrintf -C link-arg=/INCLUDE:floor, _arm64, aarc… (pull_request) Skipped
windows-host / package (x64, 0f20ce6674d4f2dbcc8c5d59fdf99f7ba45f8c3b367e0f5781cbfa30a1c78d99, bun-windows-x64-baseline.zip, --features nvenc,qsv, --features nvenc,qsv, -C target-feature=+crt-static, , x86_64-pc-windows-msvc, C:\t) (pull_request) Skipped
android / gate (pull_request) Successful in 11s
android / android (pull_request) Skipped
nix / gate (pull_request) Successful in 10s
nix / flake (pull_request) Skipped
ci / bun-nix (pull_request) Successful in 19s
ci / changes (pull_request) Successful in 24s
ci / rust-arm64 (pull_request) Skipped
ci / decky-typecheck (pull_request) Skipped
macos-host / check (pull_request) Successful in 34s
ci / docs-drift (pull_request) Successful in 45s
secret-scan / gitleaks (pull_request) Successful in 37s
ci / sdk-plugin-kit (pull_request) Successful in 50s
ci / web (pull_request) Successful in 3m30s
ci / docs-site (pull_request) Successful in 3m58s
windows-host / pr-lint (pull_request) Successful in 5m48s
windows-host / canary-manifest (pull_request) Skipped
windows-host / winget-source (pull_request) Skipped
ci / rust (pull_request) Successful in 23m24s
5ace4e57e8
A library folder holds one folder per game, and a plugin reads one small
file inside each: GOG's `goggame-<id>.info`, EA's `__Installer`, Xbox's
`Content`. Asking for the library walked every game file; asking per game
put one prompt per title before the operator.

A path may now hold one `*` component. It is a files pattern however it
was asked, so a plugin on a kit that predates `files` asks with a plain
string. The host judges it by its base, records it as asked, and places
the files ACE on the base and on each folder it names today, so one yes
covers a library and a game installed later gets its ACE at the next
converge or when the plugin asks for it. A concrete ask that a files root
or pattern already covers is opened before it is answered, so the scan
that follows can read it.

Docs name the pattern for manifests and `wants`.
enricobuehler merged commit b70aaf8a0b into main 2026-11-01 00:49:28 +00:00
Sign in to join this conversation.