feat: add permission checking via set_user/clear_user

[Koan-Bot]

Summary

• Adds opt-in Unix permission checking for mocked file operations via set_user($uid, @gids) / clear_user()
• When active, operations check owner/group/other permission bits against the mock identity

Why

Without permission checks, Test::MockFile always allows all operations regardless of file mode bits. This makes it impossible to test code that depends on permission-based behavior (e.g., read-only files, restricted directories, privilege checks).

How

• _check_perms($mock, $access) checks permission bits using the standard Unix model (owner/group/other triads)
• _check_parent_perms($path, $access) checks parent directory permissions for ops that modify directory contents
• Root (uid 0) bypasses read/write checks; execute still requires at least one x bit
• Permission checks added to: open, sysopen, opendir, unlink, mkdir, rmdir, chmod, chown
• chown uses mock identity instead of $> / $) when set_user is active
• Fully backward compatible: without set_user(), no checks occur

Testing

• 16 subtests in t/perms.t covering: basic set/clear lifecycle, owner/group/other read/write, root bypass, sysopen, opendir, parent dir checks (unlink/mkdir/rmdir), chmod ownership, chown identity, non-existent files, multiple groups, file creation parent checks

Closes #3

🤖 Generated with Claude Code

[toddr]

@Koan-Bot rebase

[Koan-Bot]

Rebase: feat: add permission checking via set_user/clear_user

Branch koan.atoomic/permission-checks-v2 rebased onto master and force-pushed.

Diff: 33 files changed, 752 insertions(+), 3373 deletions(-)

Review feedback was analyzed and applied.

Actions

• Rebased koan.atoomic/permission-checks-v2 onto upstream/master
• Force-pushed koan.atoomic/permission-checks-v2 to origin
• CI failed (attempt 1)
• Applied CI fix (attempt 1)
• Pushed CI fix (attempt 1)
• CI failed (attempt 2)
• CI still failing after 2 fix attempts

CI

CI still failing after 2 fix attempts.

Last failure logs

... (truncated)
tu	UNKNOWN STEP	2026-03-03T19:14:12.8768226Z # 	Test2::Tools::Subtest::subtest_buffered("rmdir permission checks on parent directory", CODE(0x557080315258)) called at t/perms.t line 234
ubuntu	UNKNOWN STEP	2026-03-03T19:14:12.8771771Z 
ubuntu	UNKNOWN STEP	2026-03-03T19:14:12.8772093Z # Failed test 'open > on new file checks parent directory perms'
ubuntu	UNKNOWN STEP	2026-03-03T19:14:12.8772673Z # at t/perms.t line 328.
ubuntu	UNKNOWN STEP	2026-03-03T19:14:12.8773320Z # Caught exception in subtest: You cannot set stats for nonexistent dir '/perms/wdir' at t/perms.t line 313.
ubuntu	UNKNOWN STEP	2026-03-03T19:14:12.8774162Z # 	main::__ANON__() called at /usr/local/share/perl/5.38.2/Test2/API.pm line 718
ubuntu	UNKNOWN STEP	2026-03-03T19:14:12.8774601Z # 	eval {...} called at /usr/local/share/perl/5.38.2/Test2/API.pm line 718
ubuntu	UNKNOWN STEP	2026-03-03T19:14:12.8775829Z # 	Test2::API::run_subtest("open > on new file checks parent directory perms", CODE(0x55708032ecd0), HASH(0x55707f607678)) called at /usr/local/share/perl/5.38.2/Test2/Tools/Subtest.pm line 34
ubuntu	UNKNOWN STEP	2026-03-03T19:14:12.8776879Z # 	Test2::Tools::Subtest::subtest_buffered("open > on new file checks parent directory perms", CODE(0x55708032ecd0)) called at t/perms.t line 328
ubuntu	UNKNOWN STEP	2026-03-03T19:14:12.8777472Z # Seeded srand with seed '20260303' from local date.
ubuntu	UNKNOWN STEP	2026-03-03T19:14:12.8799257Z t/perms.t ........................... 
ubuntu	UNKNOWN STEP	2026-03-03T19:14:12.8799847Z Dubious, test returned 6 (wstat 1536, 0x600)
ubuntu	UNKNOWN STEP	2026-03-03T19:14:12.8800397Z Failed 6/18 subtests 
ubuntu	UNKNOWN STEP	2026-03-03T19:14:12.9798914Z t/plugin-filetemp.t ................. ok
ubuntu	UNKNOWN STEP	2026-03-03T19:14:13.4510309Z t/plugin.t .......................... ok
ubuntu	UNKNOWN STEP	2026-03-03T19:14:13.5479269Z t/pod-coverage.t .................... ok
ubuntu	UNKNOWN STEP	2026-03-03T19:14:13.6523642Z t/pod.t .............................

---

Automated by Kōan

[toddr]

@Koan-Bot rebase

[Koan-Bot]

Rebase: feat: add permission checking via set_user/clear_user

Branch koan.atoomic/permission-checks-v2 rebased onto master and force-pushed.

Diff: 3 files changed, 557 insertions(+), 8 deletions(-)

Review feedback was analyzed and applied.

Actions

• Resolved merge conflicts (1 round(s))
• Rebased koan.atoomic/permission-checks-v2 onto upstream/master
• Force-pushed koan.atoomic/permission-checks-v2 to origin
• CI passed

CI

CI passed.

---

Automated by Kōan