Skip to content

perf(windows): opt in to batching private ACL restrictions - #8996

Open
luvs01 wants to merge 4 commits into
lidge-jun:devfrom
luvs01:codex/windows-acl-batch-restrictions
Open

luvs01 wants to merge 4 commits into
lidge-jun:devfrom
luvs01:codex/windows-acl-batch-restrictions

Conversation

@luvs01

@luvs01 luvs01 commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Windows private file publication starts icacls.exe for three permission changes on each new private entry. On a physical Windows host, updating a small Remote Link receipt spent about 0.32 s in six launches across its parent directory and temporary file.

  • Add an experimental process setting, OPENCODEX_ACL_BATCH_RESTRICTIONS=1. The owner grant still has to succeed before the second command removes inherited permissions and the same broad explicit grants. The default stays off. Elevated staging continues to use its existing sequence.
  • A failed combined command reports both operations. Its failure cannot use the split sequence's exception for an already-absent SID. Required writes retain the previous destination. The existing shared deadline, retry and async child cleanup rules still apply.
  • Keep baseline tests isolated from a developer's ambient setting. Document the option and when to return to the default in English and Spanish. The CI evidence policy preserves its 31 prior entries and appends the changed test harness fingerprint.

Verification

  • Windows x64, Bun 1.4.4. bun test on tests/windows/{windows-acl-start-cost,windows-secret-acl,windows-secret-acl-diagnostics,windows-secret-acl-removal-flight,windows-atomic-write-acl-rearm,windows-lifecycle-root-acl}.test.ts passed all 288 cases with the option in the launching environment. The opt-in cases select it explicitly after test isolation. Typecheck, structure, privacy, and diff checks passed. The full local suite was not run; local coverage targeted the two execution paths, error metadata, publication, timeout handling and cleanup. Repository-wide coverage is left to CI.
  • Added a Windows-only regression case using the real command and a separate native descriptor check on empty files and directories under a private test root. The native case, repository size/layout guards, and Spanish documentation checks passed (93 cases). The release-evidence suite passed all 26 tests.
  • Compared fresh NTFS files and directories under the same private fixture root. The split and combined commands produced identical security descriptors with inheritance disabled, including fixtures with an explicit group read grant. An independent owner/ACL check passed on the final synthetic directory and file after eight writes. Median repeat publication time on this host was 0.322 s with six launches and 0.219 s with four (seven observations per setting).
  • Integration with fix(link): restore guarded stop cleanup with native Windows owner proof #8933 at 456946c5 on the same physical Windows host and the same combined source tree: the stock bound-restart test completed in 13.21 s with the option enabled. With the option off, its existing 15 s parent watchdog fired at 15.06 s. Both runs used the original recovery assertions, child watchdog, and a fresh test home. This is one positive recovery case on one host.

Checklist

  • Scope stays focused and avoids unrelated cleanup.
  • Docs or release notes were updated when needed.
  • Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. Maintainer review of Windows permission handling is pending.

Summary by CodeRabbit

  • New Features
    • An experimental Windows option can combine inheritance removal and broad group-permission removal when restricting private files and directories. If the combined operation fails, the restriction attempt fails.
    • The option is off by default. Elevated staging keeps its separate permission sequence.
  • Documentation
    • Windows troubleshooting and configuration guides now explain the option and how to enable or disable it.

@coderabbitai

coderabbitai Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

Windows private-entry hardening now supports an opt-in combined ACL restriction command. The owner grant still runs first. When batching is disabled or extra read ACEs are present, hardening uses the existing separate operations. Windows tests and documentation cover the new option.

Changes: Windows ACL batching

Layer / File(s) Summary
Batch restriction path
src/lib/windows-secret-acl.ts, scripts/test.ts, docs-site/src/content/docs/troubleshooting/windows-acl-timeouts.md, structure/config.md
src/lib/windows-secret-acl.ts adds the combined step and gated synchronous and asynchronous paths (lines 359–361, 1010–1013, 1112–1117, 1179–1182). The owner grant precedes the combined command. The isolated test environment sets the option to "0". The documentation describes the combined command, failure handling, default sequence, and elevated-staging sequence.
Windows validation and release evidence
tests/windows/windows-acl-batched-native.test.ts, tests/windows/windows-acl-start-cost.test.ts, tests/windows/windows-secret-acl-diagnostics.test.ts, scripts/test-layout/layout.json, tests/fixtures/test-layout-expected.json, .github/scripts/release-evidence-policy.json
Windows tests check private-entry verification, synchronous and asynchronous writes, combined-command failures, diagnostics, and the separate elevated-staging sequence. The test layout and expected fixture register the new test. The release-evidence record includes 14 Windows shards and file hashes.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Merge Risk: Minimal · up to 7fdce

This adds an opt-in, default-off Windows ACL batching option with documentation and tests. The default behavior is unchanged, and no concrete merge-blocking risk was found.

Pre-merge checks: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title "perf(windows): opt in to batching private ACL restrictions" matches the main change: an experimental, default-off OPENCODEX_ACL_BATCH_RESTRICTIONS setting that combines inheritance removal …
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title "perf(windows): opt in to batching private ACL restrictions" matches the main change: an experimental, default-off OPENCODEX_ACL_BATCH_RESTRICTIONS setting that combines inheritance removal and broad-group grant removal into one icacls call for private file publication on Windows. The title is specific, concise, and follows a conventional-commit style. It does not cover the documentation, test isolation, or release-evidence updates, which is expected for a title.

Finishing Touches

Generate unit tests (beta)

  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between d61cca1 and 7fdcee7.

Files selected for processing: 11

  • .github/scripts/release-evidence-policy.json
  • docs-site/src/content/docs/es/troubleshooting/windows-acl-timeouts.md
  • docs-site/src/content/docs/troubleshooting/windows-acl-timeouts.md
  • scripts/test-layout/layout.json
  • scripts/test.ts
  • src/lib/windows-secret-acl.ts
  • structure/config.md
  • tests/fixtures/test-layout-expected.json
  • tests/windows/windows-acl-batched-native.test.ts
  • tests/windows/windows-acl-start-cost.test.ts
  • tests/windows/windows-secret-acl-diagnostics.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

✅ Deterministic PR hygiene checks passed.

@luvs01
luvs01 marked this pull request as ready for review November 20, 2026 11:54

luvs01 commented Nov 21, 2026

Copy link
Copy Markdown
Collaborator Author

A second Windows x64 measurement separates the subprocess savings from the stop-recovery deadline. I combined this head (7fdcee7e) with #8933 at 2d3a18a50 (combined tree bebef21795008ec2c8ae2d4cb1dc1a11c7645fe1, Windows build 26300.10075, Bun 1.4.4). I explicitly set the option in the test process after the standard test preload, which otherwise resets it to 0. The production default was unchanged.

In separate instrumented bound-restart runs, the disconnect phase issued 90 synchronous icacls.exe calls on #8933 alone (4.11 s total) and 60 on the combined tree with batching enabled (2.88 s). Both still made one synchronous owner/DACL verification through PowerShell during disconnect, taking about 1.5 s. In the enabled diagnostic run the restart received HTTP 202 and rebound at 16.84 s from child startup. The diagnostic did not impose the 15 s parent deadline.

With the ordinary timeouts in place, bound restart and pending disconnect hit the 15 s parent limit in both configurations; the config-lock-contention rollback passed in both. This corroborates fewer permission-tool launches. The earlier 13.21 s pass in the description and today's results are individual runs; enabling the option does not consistently put the complete Windows recovery fixture under 15 s.

@lidge-jun

Copy link
Copy Markdown
Owner

Integration status from the current maintainer batch:

  • gpt-6.1-terra review (two rounds): PASS. A failed or timed-out combined icacls call fails hardening in both the sync and async paths, so the atomic writer keeps the previous destination. The default sequence is unchanged unless the variable is exactly 1. Focused tests: 37 pass; with src/lib/windows-secret-acl.ts restored from dev, 6 opt-in and compound-failure cases fail.
  • All 27 hashes in the new release-evidence policy entry match this head and current dev, and the branch merges cleanly with current dev.
  • Non-blocking note: on a host where one of the broad SIDs cannot be resolved, the opt-in fails closed every time, while the default path tolerates that error. The troubleshooting page says to remove the setting in that case but doesn't name the cause.

Because this changes private ACL hardening and .github/scripts/release-evidence-policy.json, I'm handing it to the maintainers for security review rather than merging it in this batch.

This branch has not been deployed

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

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants