feat(find): add --help, -type b/c, -perm, -quit; fix access TOCTOU

SHELL_FEATURES.md

@@ -12,7 +12,7 @@ Blocked features are rejected before execution with exit code 2.
 - ✅ `echo [-neE] [ARG]...` — write arguments to stdout; `-n` suppresses trailing newline, `-e` enables backslash escapes, `-E` disables them (default)
 - ✅ `exit [N]` — exit the shell with status N (default 0)
 - ✅ `false` — return exit code 1
-- ✅ `find [-L] [PATH...] [EXPRESSION]` — search for files in a directory hierarchy; supports `-name`, `-iname`, `-path`, `-ipath`, `-type`, `-size`, `-empty`, `-newer`, `-mtime`, `-mmin`, `-maxdepth`, `-mindepth`, `-print`, `-print0`, `-prune`, logical operators (`!`, `-a`, `-o`, `()`); blocks `-exec`, `-delete`, `-regex` for sandbox safety
+- ✅ `find [-L] [-P] [PATH...] [EXPRESSION]` — search for files in a directory hierarchy; supports `--help`, `-name`, `-iname`, `-path`, `-ipath`, `-type` (b,c,d,f,l,p,s), `-size`, `-empty`, `-newer`, `-mtime`, `-mmin`, `-perm`, `-maxdepth`, `-mindepth`, `-print`, `-print0`, `-prune`, `-quit`, logical operators (`!`, `-a`, `-o`, `()`); blocks `-exec`, `-delete`, `-regex` for sandbox safety
 - ✅ `grep [-EFGivclLnHhoqsxw] [-e PATTERN] [-m NUM] [-A NUM] [-B NUM] [-C NUM] PATTERN [FILE]...` — print lines that match patterns; uses RE2 regex engine (linear-time, no backtracking)
 - ✅ `head [-n N|-c N] [-q|-v] [FILE]...` — output the first part of files (default: first 10 lines); `-z`/`--zero-terminated` and `--follow` are rejected
 - ✅ `help` — display all available builtin commands with brief descriptions; for detailed flag info, use `<command> --help`

allowedpaths/portable_unix.go

@@ -29,28 +29,107 @@ func FileIdentity(_ string, info fs.FileInfo, _ *Sandbox) (uint64, uint64, bool)
 	return uint64(st.Dev), uint64(st.Ino), true
 }
 
+func (r *root) accessCheck(rel string, checkRead, checkWrite, checkExec bool) (fs.FileInfo, error) {
+	// Write-only or exec-only checks (no read): single Stat + mode-bit
+	// inspection. No TOCTOU because there is only one resolution.
+	if !checkRead {
+		info, err := r.root.Stat(rel)
+		if err != nil {
+			return nil, err
+		}
+		if !effectiveHasPerm(info, false, checkWrite, checkExec) {
+			return info, os.ErrPermission
+		}
+		return info, nil
+	}
+
+	// Read checks: open-first to get an fd, then fstat the fd.
+	// O_NONBLOCK prevents blocking on FIFOs (open returns immediately
+	// even without a writer). It is harmless on regular files and dirs.
+	f, openErr := r.root.OpenFile(rel, os.O_RDONLY|syscall.O_NONBLOCK, 0)
+	if openErr != nil {
+		// OpenFile failed. Possible reasons:
+		//   - Permission denied on a regular file (kernel/ACL)
+		//   - Unopenable type (Unix socket → ENXIO/EOPNOTSUPP)
+		//   - Path does not exist or symlink escape blocked
+		//
+		// Fall back to Stat for metadata. This is NOT a TOCTOU risk:
+		// the open already failed, so there is no fd pointing to a
+		// wrong inode.
+		info, err := r.root.Stat(rel)
+		if err != nil {
+			return nil, err
+		}
+		// For regular files, the open failure is the kernel's
+		// authoritative answer (may reflect ACLs that mode bits
+		// miss). Trust it.
+		if info.Mode().IsRegular() {
+			return info, os.ErrPermission
+		}
+		// Non-regular files that can't be opened (e.g. sockets):
+		// fall back to mode-bit inspection.
+		if !effectiveHasPerm(info, checkRead, checkWrite, checkExec) {
+			return info, os.ErrPermission
+		}
+		return info, nil
+	}
+
+	// OpenFile succeeded — fstat the fd for metadata from this exact inode.
+	info, err := f.Stat()
+	closeErr := f.Close()
+	if err != nil {
+		return nil, err
+	}
+	if closeErr != nil {
+		return nil, closeErr
+	}
+
+	// For regular files, the successful open proves read permission
+	// (kernel-level, ACL-accurate). For FIFOs and directories,
+	// O_NONBLOCK open succeeds regardless of read permission, so
+	// mode-bit check is still needed.
+	if !info.Mode().IsRegular() {
+		if !effectiveHasPerm(info, checkRead, checkWrite, checkExec) {
+			return info, os.ErrPermission
+		}
+		return info, nil
+	}
+
+	// Regular file: read proven. Check write/exec if needed.
+	if checkWrite || checkExec {
+		if !effectiveHasPerm(info, false, checkWrite, checkExec) {
+			return info, os.ErrPermission
+		}
+	}
+	return info, nil
+}
+
 // effectiveHasPerm checks whether the current process has the requested
-// permission (writeMask or execMask, each a 3-bit pattern like 0222 or 0111)
-// by inspecting the file's owner/group/other permission class that applies to
-// the effective UID and GID of the running process.
+// permission by inspecting the file's owner/group/other permission class
+// that applies to the effective UID and GID of the running process.
 //
 // On Unix this uses the Stat_t from info.Sys() to determine the owning
 // UID/GID and then selects the owner, group, or other permission bits
 // accordingly.  If the type assertion fails (should not happen in practice),
 // it falls back to checking any-class bits.
-func effectiveHasPerm(info fs.FileInfo, writeMask, execMask fs.FileMode, checkWrite, checkExec bool) bool {
+func effectiveHasPerm(info fs.FileInfo, checkRead, checkWrite, checkExec bool) bool {
 	perm := info.Mode().Perm()
 
 	// Determine which permission class applies to the current process.
 	// Default to "other" bits and narrow down if we have Stat_t.
 	ownerBits := fs.FileMode(0007) // other bits by default
 	if st, ok := info.Sys().(*syscall.Stat_t); ok {
 		uid := os.Getuid()
+		if uid == 0 {
+			// Root bypasses read/write permission checks (CAP_DAC_OVERRIDE).
+			// Execute still requires at least one x bit to be set.
+			if checkExec && perm&0111 == 0 {
+				return false
+			}
+			return true
+		}
 		gid := os.Getgid()
 		switch {
-		case uid == 0:
-			// root can read/write anything; for execute, any x bit suffices.
-			ownerBits = 0777
 		case int(st.Uid) == uid:
 			ownerBits = 0700
 		case int(st.Gid) == gid:
@@ -70,14 +149,18 @@ func effectiveHasPerm(info fs.FileInfo, writeMask, execMask fs.FileMode, checkWr
 		}
 	}
 
+	if checkRead {
+		if perm&0444&ownerBits == 0 {
+			return false
+		}
+	}
 	if checkWrite {
-		// Intersect the write mask with the applicable owner bits.
-		if perm&writeMask&ownerBits == 0 {
+		if perm&0222&ownerBits == 0 {
 			return false
 		}
 	}
 	if checkExec {
-		if perm&execMask&ownerBits == 0 {
+		if perm&0111&ownerBits == 0 {
 			return false
 		}
 	}

allowedpaths/portable_windows.go

@@ -44,13 +44,44 @@ func FileIdentity(absPath string, _ fs.FileInfo, sandbox *Sandbox) (uint64, uint
 	return uint64(d.VolumeSerialNumber), uint64(d.FileIndexHigh)<<32 | uint64(d.FileIndexLow), true
 }
 
-// effectiveHasPerm checks whether the current process has the requested
-// permission on Windows.  Windows does not use Unix UID/GID permission classes,
-// so we fall back to checking any-class bits (0222 / 0111) as before.
-func effectiveHasPerm(info fs.FileInfo, writeMask, execMask fs.FileMode, checkWrite, checkExec bool) bool {
-	perm := info.Mode().Perm()
-	if checkWrite && perm&writeMask == 0 {
-		return false
-	}
-	return !(checkExec && perm&execMask == 0)
+// accessCheck verifies the path is inside the sandbox via os.Root.Stat,
+// then checks read permission by attempting to open the file through
+// os.Root. This respects NTFS ACLs — the kernel denies the open if
+// the current user lacks read permission. Named pipes cannot appear in
+// regular directories on Windows, so this cannot block.
+//
+//   - Read: verified by opening through os.Root (respects NTFS ACLs).
+//   - Write: checked via mode bits from Stat. On Windows,
+//     FILE_ATTRIBUTE_READONLY clears the write permission bits in
+//     Mode().Perm(), so mode-bit inspection is reliable.
+//   - Execute: Windows has no POSIX execute bits. The check always
+//     returns ErrPermission so that test -x behaves like a POSIX shell.
+func (r *root) accessCheck(rel string, checkRead, checkWrite, checkExec bool) (fs.FileInfo, error) {
+	info, err := r.root.Stat(rel)
+	if err != nil {
+		return nil, err
+	}
+
+	// Windows has no POSIX execute bits — always deny execute checks.
+	if checkExec {
+		return info, os.ErrPermission
+	}
+
+	// On Windows, FILE_ATTRIBUTE_READONLY clears the write permission
+	// bits in Mode().Perm(). Check them for write access.
+	if checkWrite && info.Mode().Perm()&0200 == 0 {
+		return info, os.ErrPermission
+	}
+
+	if checkRead && !info.IsDir() {
+		f, err := r.root.OpenFile(rel, os.O_RDONLY, 0)
+		if err != nil {
+			return info, os.ErrPermission
+		}
+		if err := f.Close(); err != nil {
+			return info, err
+		}
+	}
+
+	return info, nil
 }

allowedpaths/sandbox.go

@@ -87,6 +87,18 @@ func (s *Sandbox) resolve(absPath string) (*os.Root, string, bool) {
 // Access checks whether the resolved path is accessible with the given mode.
 // All operations go through os.Root to stay within the sandbox.
 // Mode: 0x04 = read, 0x02 = write, 0x01 = execute.
+//
+// On Unix, read permission for regular files is verified by attempting
+// to open through os.Root with O_NONBLOCK (fd-relative openat, respects
+// POSIX ACLs, never blocks on FIFOs). Metadata is obtained from the
+// opened fd via fstat to eliminate TOCTOU between open and stat.
+// For special files where open fails (e.g. sockets), and for write and
+// execute checks, mode-bit inspection is used on the fd-relative Stat
+// result. On Windows, the same OpenFile approach is used for read
+// checks; write and execute checks are not performed.
+//
+// All operations are fd-relative through os.Root — no filesystem path is
+// re-resolved through the mutable namespace after initial validation.
 func (s *Sandbox) Access(path string, cwd string, mode uint32) error {
 	absPath := toAbs(path, cwd)
 
@@ -102,42 +114,14 @@ func (s *Sandbox) Access(path string, cwd string, mode uint32) error {
 			continue
 		}
 
-		// Open through os.Root once. This checks read access and gives
-		// us a file descriptor for an atomic Stat (no TOCTOU window).
-		f, err := ar.root.Open(rel)
+		// accessCheck opens or stats the path through os.Root and
+		// performs the permission check (fd-relative OpenFile with
+		// O_NONBLOCK for reads on Unix, mode-bit inspection for
+		// everything else).
+		_, err = ar.accessCheck(rel, mode&0x04 != 0, mode&0x02 != 0, mode&0x01 != 0)
 		if err != nil {
-			if mode&0x04 != 0 && !IsErrIsDirectory(err) {
-				return PortablePathError(err)
-			}
-			// Read not requested, or target is a directory; fall back to Stat.
-			info, serr := ar.root.Stat(rel)
-			if serr != nil {
-				return PortablePathError(serr)
-			}
-			if !effectiveHasPerm(info, 0222, 0111, mode&0x02 != 0, mode&0x01 != 0) {
-				return &os.PathError{Op: "access", Path: path, Err: os.ErrPermission}
-			}
-			return nil
-		}
-
-		// For write and execute, use mode bits from f.Stat() on the
-		// open fd — atomic, no TOCTOU window.
-		// The sandbox is read-only so -w is informational only.
-		// effectiveHasPerm checks the permission class (owner/group/other)
-		// that applies to the current process's effective UID/GID on Unix,
-		// rather than the union of all classes.
-		if mode&0x03 != 0 {
-			info, err := f.Stat()
-			if err != nil {
-				f.Close()
-				return PortablePathError(err)
-			}
-			if !effectiveHasPerm(info, 0222, 0111, mode&0x02 != 0, mode&0x01 != 0) {
-				f.Close()
-				return &os.PathError{Op: "access", Path: path, Err: os.ErrPermission}
-			}
+			return &os.PathError{Op: "access", Path: path, Err: os.ErrPermission}
 		}
-		f.Close()
 		return nil
 	}
 	return &os.PathError{Op: "access", Path: path, Err: os.ErrPermission}