mustflow 2.116.0 → 2.116.2

package/templates/default/locales/en/.mustflow/skills/cross-platform-filesystem-safety/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.cross-platform-filesystem-safety
 locale: en
 canonical: true
-revision: 7
+revision: 9
 lifecycle: mustflow-owned
 authority: procedure
 name: cross-platform-filesystem-safety
-description: Apply this skill when file paths, directories, symlinks, reparse points, real paths, path traversal, reserved names, null bytes, NTFS alternate data streams, Windows 8.3 short names, Windows namespace prefixes, atomic file writes, temporary files, file copies, generated outputs, clone or checkout materialization, Windows/POSIX path behavior, line endings, file permissions, durable writes, failure classification, or filesystem cleanup are created, changed, reviewed, or reported.
+description: Apply this skill when file paths, URI path components, directories, file descriptors or handles, symlinks, hard links, reparse points, junctions, mount points, real paths, path traversal, reserved names, null bytes, NTFS alternate data streams, Windows 8.3 short names, Windows namespace prefixes, atomic file writes, temporary files, file copies, archive extraction, generated outputs, clone or checkout materialization, Windows/POSIX path behavior, TOCTOU safety, line endings, file permissions, durable writes, failure classification, or filesystem cleanup are created, changed, reviewed, or reported.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -26,7 +26,7 @@ metadata:
 <!-- mustflow-section: purpose -->
 ## Purpose
 
-Keep filesystem behavior safe across Windows and POSIX while preventing path traversal, symlink escapes, unsafe overwrites, stale generated output, and platform-only assumptions.
+Keep filesystem behavior safe across Windows and POSIX while preventing path traversal, symlink escapes, hard-link aliases, reparse or mount escapes, check-use races, unsafe overwrites, stale generated output, and platform-only assumptions. Treat an opened object capability and its verified identity as the security boundary; lexical normalization or path-prefix agreement is only an early rejection signal.
 
 <!-- mustflow-section: use-when -->
 ## Use When
@@ -37,6 +37,7 @@ Keep filesystem behavior safe across Windows and POSIX while preventing path tra
 - Behavior must work on Windows and POSIX path separators, drive roots, case differences, reserved names, maximum path lengths, executable extensions, line endings, permissions, or rename semantics.
 - Code or config serves files to a browser, preview server, dev server, test UI, static asset server, attachment endpoint, snapshot endpoint, or package artifact where a denied path, filename alias, or platform-specific path form could expose private files.
 - A test or final report claims a path is inside the project, symlink-safe, traversal-safe, race-safe, atomic, idempotent, cleanup-safe, or cross-platform.
+- A URL or protocol path is decoded into a filesystem path, or a queue, scanner, converter, archive extractor, or later worker reopens a path after validation.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -52,9 +53,14 @@ Keep filesystem behavior safe across Windows and POSIX while preventing path tra
 - Current filesystem helpers, path validation rules, symlink policy, case-sensitivity policy, write strategy, cleanup strategy, temporary-file strategy, permission strategy, and platform expectations.
 - Expected behavior for missing paths, existing files, directories, symlinks, dangling symlinks, reparse points or junctions, path traversal, null bytes, Windows namespace prefixes, Windows reserved names, NTFS alternate data streams, Windows 8.3 short names, trailing spaces or dots, collisions, long paths, large files, and permissions errors.
 - Path-length, filename-length, collision, staging, promotion, and cleanup expectations for clone, checkout, scaffold, install, archive, and generated-tree flows, including the deepest known entry path when available.
+- A representation ledger from raw bytes or URI component through decoder ownership and count, Unicode and separator policy, validated segments, platform path construction, and the final filesystem sink. Record every transform after validation.
+- A root-capability ledger: trusted root directory descriptor or handle, root owner and permissions, device and inode or volume and file identity where available, mount policy, symlink policy, hard-link policy, reparse-point policy, and the credential or namespace performing lookup.
+- A runtime-capability ledger: operating system, filesystem, runtime and provider version, descriptor-relative or handle-relative API actually returned, supported operations, link and mount guarantees, and any platform where the helper falls back to lexical or check-then-open behavior.
+- An operation ledger for open, create, read, write, scan, transform, rename, publish, delete, cleanup, and queued work. Record atomic flags, same-descriptor or same-handle continuity, path-only reopen points, and object identity carried between stages.
 - Failure classification expectations for filesystem and platform errors such as Windows path length, POSIX `ENAMETOOLONG`, reserved names, case collisions, Unicode aliases, file locks, permissions, quota, cross-device moves, missing executable bits, line endings, watcher limits, and descriptor limits.
 - Whether atomicity requires best-effort rename, same-directory temporary files on the same volume, file fsync, parent directory fsync, Windows replacement behavior, or reader-safe latest pointers.
 - Relevant command-intent entries for tests, docs, release, and mustflow validation.
+- Read `references/path-containment-handle-checklist.md` when untrusted paths, traversal claims, URL decoding, symlinks, hard links, junctions, mounts, TOCTOU, archive extraction, or operating-system-specific open semantics are in scope.
 
 <!-- mustflow-section: preconditions -->
 ## Preconditions
@@ -69,6 +75,7 @@ Keep filesystem behavior safe across Windows and POSIX while preventing path tra
 - Update path validation, file helpers, tests, templates, docs, and call sites needed for safe filesystem behavior.
 - Prefer repository-local safe helpers over ad hoc path string checks.
 - Do not rely on string prefix checks alone when symlinks, drive roots, or real paths matter.
+- Do not treat `normalize`, `resolve`, `absolute`, `realpath`, `GetFullPathName`, or a separator-aware prefix check as proof that the object eventually opened remains below the trusted root.
 - Do not lowercase paths as a universal containment strategy. Case-insensitive comparison may be appropriate for a specific platform boundary, but it must not collapse distinct POSIX paths or replace real containment checks.
 - Do not accept null bytes, Windows device names, namespace bypass prefixes, alternate data streams, 8.3 short-name aliases, or platform-invalid path segments as ordinary filenames.
 - Do not recursively delete, overwrite, or copy broad directories unless the target is resolved, bounded, and intentionally owned by the task.
@@ -78,43 +85,53 @@ Keep filesystem behavior safe across Windows and POSIX while preventing path tra
 <!-- mustflow-section: procedure -->
 ## Procedure
 
-1. Classify each path as trusted repository path, user input, generated state, template source, package artifact, temporary file, external path, or unknown.
-2. Reject impossible or dangerous path text early. Check null bytes, empty segments, absolute paths where relative paths are required, Windows device names such as `CON` or `NUL`, namespace prefixes such as `\\?\`, alternate data streams using colon segments, 8.3 short-name aliases such as generated `PROGRA~1`-style names, trailing dots or spaces when Windows compatibility matters, and platform-invalid characters before writing.
-3. Establish the base boundary. Use normalized repository-relative paths for storage and real-path checks for filesystem safety when symlinks may be present.
-4. Use Unicode normalization for validation only when detecting platform aliases such as superscript Windows device-name variants. Do not rewrite or persist normalized filenames unless the repository policy explicitly says so.
-5. For externally sourced trees, use a `preflight -> dangerous operation -> classifier -> safe cleanup` pipeline. Estimate the materialized path budget before writing, including destination root, project directory, generated subdirectories, deepest known repository or archive entry, Windows path-length behavior, POSIX path and component limits, byte limits, case collisions, reserved names, and safety headroom.
-6. For Git clone and checkout materialization, prefer an app-owned staging directory and no-checkout or metadata-first flow when feasible. Inspect repository entries before checkout, check them against the final destination, then promote the result only after success. Do not delete a user-selected final destination when checkout fails.
-7. For Windows Git checkout or clone materialization, prefer a per-invocation `core.longpaths=true` setting when product code invokes Git. Do not mutate global Git config from application code unless the user explicitly chose that setup action. Long-path support still depends on operating-system, Git, filesystem, and downstream tool behavior, so checkout failures must remain classifiable.
-8. For symlink-heavy repositories on Windows, detect whether checkout produced real links or plain-text symlink stubs before running build logic. Report missing Developer Mode, `core.symlinks`, or native symlink support as an environment prerequisite; do not silently replace file symlinks with junctions or copies unless the repository contract explicitly supports that compatibility mode.
-9. For POSIX, do not assume that forward slashes make paths safe. Check `ENAMETOOLONG`, byte-based per-component name limits, mount permissions, executable bits, case-sensitive import paths, symlink loops, file descriptor limits, watcher limits, quota, and cross-device rename behavior.
-10. Check containment with path-aware logic. Prefer relative-path or resolved-path containment helpers over raw string prefixes, and include a path-separator boundary so partial path traversal cannot let sibling names masquerade as children. Apply deny rules to the same canonical path form that will be opened, not to a raw URL or display path that the operating system may reinterpret.
-11. Check case behavior explicitly. Windows and many macOS volumes preserve case but compare case-insensitively by default; POSIX commonly compares case-sensitively. State whether the code preserves spelling, rejects conflicting names, or relies on the host filesystem.
-12. Check collisions before materializing Git trees, archives, generated files, uploaded names, or dependency trees. Include case-only collisions, Unicode normalization aliases, reserved Windows names with extensions, trailing dot or space aliases, duplicate archive entries, and byte-limit collisions from multibyte names.
-13. Check symlink, reparse point, and junction behavior explicitly. Decide whether they are rejected, followed only within the root, or treated as ordinary path entries. Test dangling, outside-target, loop, text-stub, and junction-like cases when relevant.
-14. Close time-of-check to time-of-use gaps where practical. Prefer opening or writing through safe helpers that reject symlinks at the final operation, then verify the opened target when the platform and helper support it.
-15. Treat high-level path APIs as incomplete defenses when the runtime cannot expose descriptor-relative open, no-follow, or opened-file verification. Do not claim race-free behavior from resolve-then-open code alone.
-16. Check traversal and root handling across platforms. Account for absolute paths, drive letters, UNC-like paths, mixed separators, empty paths, dot segments, reserved names, long paths, case sensitivity, NTFS alternate data streams, 8.3 short names, and Windows namespace prefixes where relevant.
-17. Classify filesystem failures before generic network, auth, or unknown failures. Use stable categories such as `path_too_long`, `filename_too_long`, `byte_limit_exceeded`, `invalid_path`, `reserved_name`, `case_collision`, `unicode_collision`, `symlink_escape`, `permission_denied`, `file_locked`, `cross_device_move`, `disk_full_or_quota`, `executable_bit_missing`, `line_ending_mismatch`, `watcher_limit`, and `descriptor_limit`.
-18. For writes, prefer same-directory temporary-file then rename or replace behavior when readers may observe the file. Keep the temporary file on the same volume, use unpredictable names, least-privilege creation permissions, and safe no-follow writes when the project already has that helper.
-19. Treat atomic writes as platform-specific. POSIX rename semantics, Windows replacement behavior, cross-filesystem moves, network filesystems, fsync availability, and directory fsync support differ; report best-effort guarantees honestly.
-20. When durable writes matter, include the full durability sequence where the platform supports it: write the temporary file, flush the file data, close it, rename or replace it, then flush the parent directory entry. If parent directory fsync is unavailable, downgrade the durability claim.
-21. For copies and updates, close the check-then-write gap as much as the platform and existing helpers allow. Do not report symlink safety if the final write can still follow a changed symlink.
-22. For privileged Windows services, check whether reparse-point traversal mitigations belong at process startup. If the code cannot enable or verify them, report the remaining junction risk instead of claiming system-level protection.
-23. For host environment limitations such as long-path registry flags, Developer Mode, WSL metadata mounts, Linux inotify/sysctl limits, Docker Desktop volume backend, or antivirus locks, classify and report the environment prerequisite. Do not perform privileged host repair from ordinary file logic.
-24. Distinguish disk and quota errors from watch or descriptor exhaustion. In a watcher or scanner path, `ENOSPC` may mean an inotify watch limit rather than a full disk, and `EMFILE` or similar failures may indicate a per-process or per-user file-descriptor limit.
-25. For deletes and cleanup, verify the resolved absolute target is inside the intended generated or temporary directory and narrow the deletion scope. Preserve bounded diagnostic evidence before deleting partial clone, checkout, scaffold, install, extraction, or generated output. Cleanup may remove only app-owned staging or generated-state paths, never the user-selected destination that the operation was supposed to populate.
-26. For scans, bound recursion, generated/vendor exclusions, file size, symlink traversal, reparse-point traversal, loop detection, and maximum path length or depth where relevant.
-27. Keep path output stable for users and automation. Report repository-relative paths unless an absolute path is necessary for local diagnosis.
-28. Add focused tests for the highest-risk path shapes and failure categories instead of broad platform speculation.
+1. Classify each path as trusted repository path, untrusted protocol input, generated state, template source, package artifact, temporary file, external path, or unknown. Prefer an opaque object identifier or server-generated single filename over accepting a path hierarchy.
+2. Build the representation ledger before changing validation. For URL-like input, parse the protocol and select the path component first, decode that component exactly once under one named owner, apply the declared Unicode and separator policy, split into segments, validate the segments, freeze the validated representation, and only then construct the platform path. Reject a second decoder or any post-validation transform that can create a separator, dot segment, NUL, device name, namespace, or alternate stream.
+3. Reject impossible or dangerous path text early. When a pure relative path is required, reject empty, `.` and `..` segments instead of normalizing them away. Check null bytes after decoding, absolute and root-relative forms, drive-relative forms such as `C:tmp`, UNC and device namespaces, Windows device names such as `CON` or `NUL`, namespace prefixes such as `\\?\` and `\\.\`, alternate data streams using colon segments, trailing dots or spaces, and platform-invalid characters.
+4. Use Unicode normalization for validation only when detecting platform aliases such as superscript Windows device-name variants. Do not rewrite or persist normalized filenames unless the repository policy explicitly says so. Validate for the filesystem that will consume the path, not only the upstream host.
+5. Establish the trusted root as an already opened directory descriptor or handle when the risk requires strong containment. Record its owner, permissions, namespace, device or volume identity, and whether attackers can rename or add children below it. Do not make current working directory part of the security decision.
+6. Use lexical normalization, separator-aware relative checks, prefix checks, and `realpath` only for early rejection, diagnostics, and low-risk trusted paths. Keep separator boundaries so partial path traversal cannot make a sibling name look like a child, but do not mistake that lexical check for proof across a later lookup, symlink, junction, reparse point, mount, hard link, or attacker-controlled parent.
+7. On Linux where the runtime exposes it, resolve untrusted paths relative to the trusted root descriptor with `openat2`. Choose `RESOLVE_BENEATH` or `RESOLVE_IN_ROOT` deliberately, add `RESOLVE_NO_MAGICLINKS` explicitly when magic links are forbidden, add `RESOLVE_NO_XDEV` when mount crossings are forbidden, and add `RESOLVE_NO_SYMLINKS` only when all symlinks are forbidden. Do not present `O_NOFOLLOW` as an all-component defense; it affects only the final component.
+8. Prefer an audited runtime root-capability API when it preserves the needed operation on the actual platform. Go `os.Root` or `os.OpenInRoot` can provide root-relative operations, but its guarantees vary by target: it does not block Unix mount traversal, and targets without descriptor-relative support may retain check-use limitations. Java `SecureDirectoryStream` is useful only when the installed filesystem provider and operating system actually return that interface. Otherwise use an audited helper that walks one segment at a time relative to directory descriptors, opens intermediate directories with directory and no-follow constraints, and never reconstructs an absolute path mid-walk. Record the runtime, provider, filesystem, supported operation, and fallback limitation instead of claiming equivalence to `openat2`.
+9. On Windows, prefer an opaque single filename below an application-owned directory. Reject drive-relative, root-relative, UNC, device-namespace, alternate-stream, reserved-device, trailing-dot, trailing-space, and mixed-separator aliases before opening. Open a HANDLE with the intended reparse behavior, inspect the opened object's reparse tag, final path, volume identity, and file identity where the API and runtime expose them, and use that same HANDLE for the operation. Do not claim that `GetFullPathName`, a final path string, or ordinary `CreateFile` behavior is a Windows equivalent of `openat2`.
+10. Reject reparse points and junctions by default in attacker-writable trees unless the product has an explicit allow policy and can verify the opened target. For privileged Windows services, check whether process-level reparse traversal mitigations belong at startup; if the code cannot enable and verify them, report the remaining risk.
+11. Open first under the path-resolution policy, inspect the opened object with `fstat` or the corresponding handle metadata, then read, write, scan, transform, or publish through that same descriptor or handle. `exists`, `access`, `lstat`, `realpath`, or metadata-check followed by an unrelated `open` is a time-of-check to time-of-use gap.
+12. Treat hard links separately from symlinks. No-follow flags do not stop a hard link from naming an existing file. Where the policy forbids shared identities, verify device and inode or volume and file identity, consider link count as one signal, and ensure attackers cannot create links in the storage directory. Do not claim link-count checks alone prove ownership.
+13. Treat mount boundaries separately from path boundaries. Use `RESOLVE_NO_XDEV`, mount identity, volume identity, or an equivalent owned-storage invariant when mount or bind-mount crossings are forbidden. State explicit compatibility exceptions for legitimate mount layouts.
+14. Create new objects through the trusted parent descriptor or handle with one validated final segment and an atomic exclusive-create primitive such as `O_CREAT|O_EXCL` or `CREATE_NEW`. Do not precheck existence and then create.
+15. For scanners, converters, antivirus, image processors, and other path-only tools, materialize an immutable application-owned staging object first. Bind the result to an object identifier, digest, size, and generation, and reject any stage that silently reopens an attacker-controlled path.
+16. For queued work, store an immutable object identity, digest, and generation rather than a previously validated path. Reauthorize and revalidate the current object version at execution time; a queue delay turns a path string into stale authority.
+17. For archive extraction, parse and validate the complete entry set before the first write when the format and bounded input permit it. Build one destination graph that rejects duplicate and platform-alias names, file-versus-directory prefix conflicts such as `a` and `a/b`, separator and Unicode collisions, and order-dependent link traversal. Carry the validated entry object into extraction instead of reparsing the raw name. Accept only regular files and directories by default; reject symlink, hard-link, device, FIFO, socket, reparse, and other special entries unless an explicit product contract proves them safe. Ignore archive-supplied owner, group, mode, setuid, setgid, sticky, ACL, xattr, capability, and timestamp metadata unless each field is allowlisted, and create files with service-owned permissions. Count actual emitted bytes, logical file size, allocated temporary storage, sparse extents, entry count, directories, depth, name length, compression work, nested archives, and elapsed time under one shared budget. Create every entry through the trusted root capability and use `file-upload-security-review` for the surrounding upload, parser, storage, serving, and cleanup lifecycle.
+18. For externally sourced trees, use a `preflight -> dangerous operation -> classifier -> safe cleanup` pipeline. Estimate the materialized path budget before writing, including destination root, project directory, generated subdirectories, deepest known repository or archive entry, Windows path-length behavior, POSIX path and component limits, byte limits, case collisions, reserved names, and safety headroom.
+19. For Git clone and checkout materialization, prefer an app-owned staging directory and no-checkout or metadata-first flow when feasible. Inspect repository entries before checkout, check them against the final destination, then promote the result only after success. Do not delete a user-selected final destination when checkout fails.
+20. For Windows Git checkout or clone materialization, prefer a per-invocation `core.longpaths=true` setting when product code invokes Git. Do not mutate global Git config from application code unless the user explicitly chose that setup action. Long-path support still depends on operating-system, Git, filesystem, and downstream tool behavior, so checkout failures must remain classifiable.
+21. For symlink-heavy repositories on Windows, detect whether checkout produced real links or plain-text symlink stubs before running build logic. Report missing Developer Mode, `core.symlinks`, or native symlink support as an environment prerequisite; do not silently replace file symlinks with junctions or copies unless the repository contract explicitly supports that compatibility mode.
+22. For POSIX, do not assume that forward slashes make paths safe. Check `ENAMETOOLONG`, byte-based per-component name limits, mount permissions, executable bits, case-sensitive import paths, symlink loops, file descriptor limits, watcher limits, quota, and cross-device rename behavior.
+23. Check case behavior explicitly. Windows and many macOS volumes preserve case but compare case-insensitively by default; POSIX commonly compares case-sensitively. State whether the code preserves spelling, rejects conflicting names, or relies on the host filesystem.
+24. Check collisions before materializing Git trees, archives, generated files, uploaded names, or dependency trees. Include case-only collisions, Unicode normalization aliases, reserved Windows names with extensions, trailing dot or space aliases, duplicate archive entries, and byte-limit collisions from multibyte names.
+25. Classify filesystem failures before generic network, auth, or unknown failures. Use stable categories such as `path_too_long`, `filename_too_long`, `byte_limit_exceeded`, `invalid_path`, `reserved_name`, `case_collision`, `unicode_collision`, `symlink_escape`, `mount_escape`, `identity_mismatch`, `permission_denied`, `file_locked`, `cross_device_move`, `disk_full_or_quota`, `executable_bit_missing`, `line_ending_mismatch`, `watcher_limit`, and `descriptor_limit`.
+26. For writes, prefer same-directory temporary-file then rename or replace behavior when readers may observe the file. Keep the temporary file on the same volume, use unpredictable names, least-privilege creation permissions, and safe no-follow writes when the project already has that helper. For hostile tree materialization, use a new attacker-nonwritable staging directory with private Unix permissions or a dedicated Windows ACL, then publish only the verified tree.
+27. Treat atomic writes as platform-specific. POSIX rename semantics, Windows replacement behavior, cross-filesystem moves, network filesystems, FUSE or overlay filesystems, fsync availability, and directory fsync support differ; report best-effort guarantees honestly.
+28. When durable writes matter, include the full durability sequence where the platform supports it: write the temporary file, flush the file data, close it, rename or replace it, then flush the parent directory entry. If parent directory fsync is unavailable, downgrade the durability claim.
+29. For copies and updates, keep the source and destination descriptors open through the operation where feasible. Do not report symlink safety if the final write or later consumer can still follow a changed link or reopen a mutable path.
+30. Treat rename and delete as name-to-parent operations with their own races. Strong claims require an attacker-nonwritable parent or a platform primitive that binds the operation to the intended parent and object identity. Prefer atomic quarantine into application-owned storage before destructive cleanup; do not claim that a prior opened-handle check alone makes a later path-based delete safe.
+31. For host environment limitations such as long-path registry flags, Developer Mode, WSL metadata mounts, Linux inotify/sysctl limits, Docker Desktop volume backend, network filesystems, or antivirus locks, classify and report the environment prerequisite. Do not perform privileged host repair from ordinary file logic.
+32. Distinguish disk and quota errors from watch or descriptor exhaustion. In a watcher or scanner path, `ENOSPC` may mean an inotify watch limit rather than a full disk, and `EMFILE` or similar failures may indicate a per-process or per-user file-descriptor limit.
+33. For deletes and cleanup, narrow the target to app-owned staging or generated state. Preserve bounded diagnostic evidence first, then revalidate the operation at the destructive boundary. Never remove the user-selected destination that the operation was supposed to populate.
+34. For scans, bound recursion, generated/vendor exclusions, file size, symlink, hard-link, reparse-point and mount traversal, loop detection, maximum path length, depth, entry count, and total bytes.
+35. Keep path output stable for users and automation. Report repository-relative display paths separately from security identities; never reuse a display path as authorization.
+36. Add focused tests for decode order and double decoding, NUL after decode, dot segments, mixed separators, drive-relative and namespace forms, alias collisions, middle and final symlink swaps, hard links, bind mounts, junctions and reparse points, exclusive-create collisions, same-handle identity, queued stale paths, destructive-operation races, archive order attacks, file-directory prefix conflicts, metadata restoration attempts, sparse logical-size exhaustion, runtime-provider fallback, and unsupported-filesystem behavior.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
-- Path boundaries, invalid-name policy, case policy, symlink and reparse-point policy, write strategy, cleanup strategy, durability expectations, and platform assumptions are explicit.
-- Clone, checkout, scaffold, install, extraction, and generated-tree flows have preflight, staging, promotion, path-length, byte-limit, symlink-stub, collision, diagnostic-preservation, cleanup, and failure-taxonomy policies.
+- The chain from raw representation through one decoder, immutable validated segments, trusted root capability, opened object identity, and same-descriptor or same-handle operation is explicit.
+- Runtime and provider capability claims identify the actual platform implementation and do not silently promote lexical or check-then-open fallbacks to race-resistant guarantees.
+- Path boundaries, invalid-name policy, case policy, symlink, hard-link, reparse-point, junction, and mount policy, write strategy, cleanup strategy, durability expectations, and platform assumptions are explicit.
+- Clone, checkout, scaffold, install, extraction, and generated-tree flows have preflight, whole-entry collision mapping, metadata policy, staging, promotion, path-length, logical and emitted-byte limits, symlink-stub, collision, diagnostic-preservation, cleanup, and failure-taxonomy policies.
 - Host setting prerequisites are reported without unapproved registry, global config, WSL, sysctl, Docker Desktop, antivirus, or shell-profile mutation.
 - Dangerous file operations are bounded to known repository-owned or generated locations.
-- Atomicity and race-safety claims are scoped to what the current helpers and platform can actually guarantee.
+- Atomicity, containment, identity, and race-safety claims are scoped to what the current helpers, kernel, runtime, and filesystem can actually guarantee.
 - Any untested platform behavior is reported as remaining risk instead of claimed safe.
 
 <!-- mustflow-section: verification -->
@@ -135,6 +152,7 @@ Use release checks when template files, package artifacts, or installed workflow
 ## Failure Handling
 
 - If root containment is unclear, stop before writing or deleting and report the ambiguous path owner.
+- If validation and use cannot share an opened descriptor, handle, or immutable object identity, fail closed for hostile paths or report the exact reopen race.
 - If the platform cannot prove symlink-safe behavior, fail closed or document the exact remaining gap.
 - If atomic replace, file fsync, parent directory fsync, no-follow open, or final-target verification is not available on the platform, downgrade the claim to best-effort and keep the write boundary narrow.
 - If Unicode normalization, Windows namespace prefixes, alternate data streams, 8.3 short names, or reparse points could change the effective target, fail closed or report the exact unhandled path class.
@@ -148,8 +166,9 @@ Use release checks when template files, package artifacts, or installed workflow
 
 - Filesystem surface reviewed
 - Path trust classes, invalid-name handling, case policy, and root boundary
-- Null byte, reserved-name, Unicode normalization, namespace prefix, alternate data stream, 8.3 short-name, symlink, reparse-point, traversal, race, atomic write, durability, permission, copy, delete, scan, and cleanup decisions
-- Clone, checkout, scaffold, install, extraction, preflight, staging, promotion, path-length, collision, failure-taxonomy, and diagnostic-preservation decisions
+- Decode and representation ledger; trusted root capability; opened-object identity; same-descriptor or same-handle continuity
+- Null byte, reserved-name, Unicode normalization, namespace prefix, alternate data stream, 8.3 short-name, symlink, hard-link, mount, reparse-point, traversal, race, atomic write, durability, permission, copy, queue, delete, scan, and cleanup decisions
+- Clone, checkout, scaffold, install, extraction, whole-entry collision graph, archive metadata, sparse-file budget, runtime capability, preflight, staging, promotion, path-length, collision, failure-taxonomy, and diagnostic-preservation decisions
 - Host-setting prerequisites reported or deferred
 - Windows/POSIX assumptions and skipped platform checks
 - Tests or fixtures added or reused

package/templates/default/locales/en/.mustflow/skills/cross-platform-filesystem-safety/references/path-containment-handle-checklist.md

@@ -0,0 +1,251 @@
+# Path Containment and Opened-Object Checklist
+
+Use this reference when a filesystem boundary accepts untrusted names, decodes URL components, crosses process or queue stages, extracts archives, or claims resistance to traversal, links, mounts, or check-use races.
+
+## Contents
+
+1. Security pipeline
+2. Representation and decode ledger
+3. Pure-relative segment policy
+4. Windows lexical hazards
+5. Root capability and object identity
+6. Linux resolution policy
+7. POSIX fallback boundaries
+8. Windows HANDLE and reparse policy
+9. Hard-link and mount identity
+10. TOCTOU operation matrix
+11. Creation, staging, publication, deletion, and queues
+12. Archive extraction
+13. Test matrix
+14. Primary anchors
+
+## 1. Security Pipeline
+
+Use this order for hostile input:
+
+`raw bytes -> protocol parse -> select one path component -> strict decode once -> Unicode and separator policy -> segment validation -> immutable relative representation -> lookup below trusted root -> validate opened object -> operate through the same descriptor or handle`
+
+Every arrow needs one owner. A second decoder, normalizer, separator conversion, case fold, Unicode rewrite, environment expansion, archive library, shell, or downstream tool after validation can create a new path language and invalidate the earlier decision.
+
+Prefer an opaque object identifier and server-generated storage name. Accept a hierarchy only when the product actually needs user-selected hierarchy.
+
+## 2. Representation and Decode Ledger
+
+Record:
+
+| Stage | Questions |
+| --- | --- |
+| Transport | Are inputs bytes, a URL, a URL path component, form data, JSON, a header, or an archive entry? |
+| Parser | Which parser owns component boundaries? Is a whole URL ever decoded before parsing? |
+| Decoder | Which component is decoded, how many times, and how are malformed sequences handled? |
+| Unicode | Is normalization used only for alias detection, or does it rewrite the stored name? |
+| Separators | Which characters become separators on the final sink platform? Can a later layer reinterpret `/`, `\\`, `%2f`, `%5c`, or lookalikes? |
+| Segments | Are empty, `.`, `..`, NUL, absolute, rooted, namespace, stream, and reserved segments rejected? |
+| Construction | Is the validated immutable segment list combined only with a trusted root capability? |
+| Sink | Which kernel, filesystem, container namespace, network share, archive library, or Windows API performs the final lookup? |
+
+Do not decode the entire URI before locating its components. Do not validate encoded text and then decode it. Do not decode repeatedly until the text stops changing.
+
+## 3. Pure-Relative Segment Policy
+
+For an untrusted path below a fixed root:
+
+- require a non-empty relative segment sequence;
+- reject empty segments when duplicate separators are not part of the contract;
+- reject `.` and `..` rather than repairing them with normalization;
+- reject NUL after decoding;
+- reject absolute, root-relative, drive-relative, UNC, and device-namespace forms;
+- reject a segment that the final filesystem aliases to a reserved or different name;
+- freeze the accepted segment sequence so downstream layers cannot reinterpret raw input;
+- keep display spelling separate from the object identity used for authorization.
+
+Lexical rejection reduces attack surface. It does not replace kernel-constrained lookup.
+
+## 4. Windows Lexical Hazards
+
+Check the final Windows sink for:
+
+- both slash directions as potential separators;
+- drive-absolute paths such as `C:\\x` and drive-relative paths such as `C:x`;
+- root-relative paths such as `\\x`;
+- UNC shares and device or extended namespaces such as `\\\\server\\share`, `\\\\?\\`, and `\\\\.\\`;
+- NTFS alternate data streams introduced by colon syntax;
+- reserved device names, including device names followed by extensions and documented superscript-digit aliases;
+- trailing spaces and periods that Win32 or shell layers may trim or alias;
+- short 8.3 aliases when the volume generates them;
+- case and Unicode aliases under the actual volume policy;
+- reparse points, junctions, mount folders, and volume changes;
+- final consumer APIs that may apply different normalization or namespace rules.
+
+`GetFullPathName` computes a path string. It does not freeze the directory tree or prove what a later open reaches.
+
+## 5. Root Capability and Object Identity
+
+Treat the trusted root as a capability, not a string:
+
+- open the root directory before processing hostile names;
+- keep the root descriptor or HANDLE alive for the operation;
+- record which principal and mount or volume namespace opened it;
+- ensure attackers cannot replace the root or mutate its parent;
+- resolve children relative to that root where the platform supports it;
+- inspect the opened target rather than trusting the requested spelling;
+- carry the opened descriptor, HANDLE, or immutable object identity into later stages.
+
+Useful identity signals include POSIX device and inode, mount identity, Windows volume serial or volume identity, file ID, object type, reparse tag, and final path from an already opened HANDLE. No one signal is universally sufficient; select the set that proves the repository's policy.
+
+## 6. Linux Resolution Policy
+
+When Linux `openat2` is available through the runtime or an audited native helper, choose resolution flags by policy:
+
+| Policy | Resolution decision |
+| --- | --- |
+| A relative path must not escape the root | Resolve relative to the root `dirfd` with `RESOLVE_BENEATH`. |
+| Absolute-looking input and absolute symlinks should be scoped as if the root were `/` | Consider `RESOLVE_IN_ROOT`; do not combine its different semantics with a `BENEATH` claim. |
+| Magic links are forbidden | Add `RESOLVE_NO_MAGICLINKS` explicitly. Do not rely on another flag's current incidental behavior. |
+| All symlinks are forbidden | Add `RESOLVE_NO_SYMLINKS`; note that this also forbids legitimate symlink layouts. |
+| Mount and bind-mount crossings are forbidden | Add `RESOLVE_NO_XDEV`; document legitimate mount compatibility exceptions. |
+| Only the final component must not be a symlink | `O_NOFOLLOW` can enforce that narrower rule, but not all-component safety. |
+
+Handle `EAGAIN`, `EXDEV`, `ELOOP`, unsupported-kernel behavior, and runtime wrapper gaps explicitly. Bound retries for race-related `EAGAIN`; never fall back silently to an unconstrained absolute open.
+
+## 7. POSIX Fallback Boundaries
+
+If `openat2` is unavailable:
+
+1. Start from an opened trusted root directory descriptor.
+2. Walk one validated segment at a time with descriptor-relative operations.
+3. Open intermediate components as directories and reject symlink following.
+4. Keep the current directory descriptor alive until the next descriptor is secured.
+5. Apply the final operation relative to the verified parent descriptor.
+6. Inspect the opened object and operate through that same descriptor.
+
+An audited fallback still needs tests for renames, mount changes, network filesystems, FUSE, overlay filesystems, and runtime flag support. A language runtime that only exposes `realpath` plus path-based `open` cannot honestly claim the same boundary.
+
+### Runtime root-capability APIs
+
+Use runtime helpers only after proving what the deployed platform returns:
+
+| Runtime API | Useful boundary | Required caveat |
+| --- | --- | --- |
+| Go `os.Root` or `os.OpenInRoot` | Root-relative file operations with traversal-resistant behavior on supported targets. | Record the Go version and target. Unix mount and bind-mount traversal is not blocked; GOOS targets without descriptor-relative primitives can retain TOCTOU limits; WASI inherits implementation quality. |
+| Java `SecureDirectoryStream` | Relative open, attribute, move, and delete operations through an open directory stream, with `NOFOLLOW_LINKS` where specified. | Support depends on the operating system and filesystem provider. Check that `Files.newDirectoryStream` actually returns `SecureDirectoryStream`; do not cast or claim support blindly. |
+| High-level path helper only | Lexical rejection and diagnostics. | `normalize`, `realpath`, `abspath`, or prefix comparison does not become a root capability merely because the runtime documents it as safe for ordinary paths. |
+
+For every wrapper, inventory open, exclusive create, mkdir, rename, delete, stat, and link behavior separately. A wrapper that safely opens files may still lack a parent-bound rename or delete primitive.
+
+## 8. Windows HANDLE and Reparse Policy
+
+Windows does not have a drop-in `openat2` equivalent. Keep the claim narrow:
+
+1. Prefer an application-owned directory whose parents are not attacker-writable.
+2. Prefer one server-generated child name rather than a user hierarchy.
+3. Reject lexical namespaces, streams, rooted forms, separators, reserved aliases, and trailing-dot or trailing-space forms before opening.
+4. Open a HANDLE with the access, sharing, creation disposition, and reparse behavior intended by the policy.
+5. Inspect metadata from that opened HANDLE: object type, attributes and reparse tag, final path, volume identity, and file identity where available.
+6. Reject reparse points by default in an untrusted tree unless the product explicitly follows and verifies them.
+7. Use the same HANDLE for I/O. Do not validate the HANDLE and then reopen the original path.
+8. For creation, use an atomic exclusive disposition such as `CREATE_NEW`; do not call an existence check first.
+
+Opening a reparse point itself and opening its target are different operations. The implementation must state which object it inspects and which object it later uses.
+
+## 9. Hard-Link and Mount Identity
+
+No-follow policies address path redirection through symbolic links or reparse points. They do not stop a hard link from naming the same underlying file.
+
+For storage that must not share identities with outside objects:
+
+- keep the storage directory non-writable by attackers;
+- compare device and inode or volume and file identity where a known expected object exists;
+- use link count only as a warning or policy signal, not a universal proof;
+- control who can create links and where;
+- use a private staging filesystem or object store when ownership cannot be established.
+
+Mounts and bind mounts can redirect a lexically contained path into a different filesystem. Use a no-cross-device resolution policy or verify mount or volume identity when that crossing is forbidden. Be explicit when container, Kubernetes, WSL, network-share, or application layouts require legitimate crossings.
+
+## 10. TOCTOU Operation Matrix
+
+| Weak sequence | Safer contract |
+| --- | --- |
+| `exists -> open` | Attempt the intended open directly and classify the result. |
+| `lstat -> open` | Open under the resolution policy, inspect the opened object, use the same descriptor. |
+| `realpath -> startsWith -> open` | Resolve below the trusted root capability and keep the returned descriptor or HANDLE. |
+| `scan(path) -> publish(path)` | Scan an immutable staging object and publish that exact object or verified digest and generation. |
+| `validate(path) -> enqueue(path)` | Enqueue immutable object ID, digest, size, and generation; reauthorize on execution. |
+| `validate -> create` | Exclusive create through the trusted parent descriptor or HANDLE. |
+| `open -> close -> delete(path)` | Quarantine atomically into attacker-nonwritable storage, or use a parent-and-identity-bound delete primitive where available. |
+
+Shortening the time window is not a proof. The design should remove the second name lookup or bind it to the same trusted parent and object identity.
+
+## 11. Creation, Staging, Publication, Deletion, and Queues
+
+- Create below a trusted parent with exactly one validated final segment and atomic exclusivity.
+- Use private, least-privilege, unpredictable staging names on the same filesystem when same-filesystem atomic promotion is required.
+- Feed scanners and converters an opened descriptor or immutable staging object. If a tool accepts only paths, make that path application-owned and non-replaceable by the attacker.
+- Bind scan and transform results to a digest, size, object ID, and generation.
+- Publish by atomic same-filesystem rename or replacement only when the target platform and filesystem contract supports the claimed reader behavior.
+- Do not claim cross-filesystem copy-and-delete is atomic.
+- Treat deletion and rename as separate security-sensitive operations. A verified read handle does not automatically authorize a later path-based delete.
+- Put immutable object identity in queues and receipts. A pathname is a mutable locator, not durable authority.
+
+## 12. Archive Extraction
+
+Before the first write, parse the complete bounded entry set when feasible and build one immutable extraction plan. Reject:
+
+- duplicate raw or normalized destinations;
+- case, Unicode, separator, reserved-name, trailing-dot, trailing-space, and 8.3 aliases under the final consumer platform;
+- file-versus-directory prefix conflicts such as a regular file `a` plus `a/b`;
+- an entry whose type or link target changes the meaning of a later entry;
+- undecodable or ambiguous names instead of repairing them;
+- a plan whose own entry count, name bytes, or graph size exceeds budget.
+
+Carry the validated entry object into extraction. Do not validate one parsed name and ask another library layer to parse the raw name again.
+
+For every planned entry:
+
+- parse the archive format once and inspect the declared entry type;
+- reject absolute, rooted, drive-relative, namespace, stream, empty, `.` and `..` segment forms;
+- apply final-platform separator and alias rules;
+- reject duplicate names plus case, Unicode, reserved-name, trailing-dot, trailing-space, and 8.3 collisions;
+- reject symlink, hard-link, device, FIFO, socket, reparse, and other special entries unless the product has an explicit safe policy;
+- create directories and files through the trusted extraction root capability;
+- use atomic exclusive creation and reject a destination that already exists;
+- never extract first and inspect later in an attacker-visible destination;
+- ignore archive-supplied uid, gid, owner names, mode, setuid, setgid, sticky bits, ACLs, xattrs, capabilities, and timestamps unless each field is explicitly required and safely allowlisted;
+- create with service-owned permissions inside a fresh attacker-nonwritable staging directory;
+- enforce entry count, directory count, name length, depth, actual total emitted bytes, per-entry bytes, logical file size, allocated temporary storage, sparse extents, compression work, CPU or time, and nested-archive budgets;
+- publish only a fully verified app-owned staging tree.
+
+Treat library filters and non-local-path warnings as versioned defense in depth. Pin the runtime and archive API behavior, set security options explicitly where available, and keep the application entry-type, collision, root-capability, metadata, and resource policies independent of library defaults.
+
+## 13. Test Matrix
+
+Cover the strongest claim with deterministic tests and platform-specific integration tests where possible:
+
+- percent-encoded separators, dot segments, malformed encoding, double decoding, and NUL after decoding;
+- mixed separators, `C:relative`, root-relative, UNC, device namespaces, alternate streams, reserved names, trailing spaces or dots, short aliases, case and Unicode collisions;
+- a symlink in a middle component, final-component symlink, dangling link, loop, magic link, junction, reparse point, bind mount, and volume crossing;
+- hard-link identity and link-count policy;
+- archive entry-order swaps, file-directory prefix conflicts, duplicate parser views, metadata restoration attempts, and sparse logical-size exhaustion;
+- attacker swaps a component between validation and open;
+- attacker swaps a path after enqueue, scan, or transform;
+- exclusive-create collision and attacker-controlled parent;
+- opened-object identity remains constant through read, scan, transform, and publish;
+- delete or rename races and quarantine behavior;
+- network filesystem, FUSE, overlay, WSL, or unsupported-runtime behavior is rejected or reported rather than silently downgraded.
+- Go or Java runtime/provider fallback is detected and the claim is narrowed instead of silently using path-only operations.
+
+Do not invent success-rate, timing, or race-frequency thresholds. A single permitted counterexample falsifies a universal containment or race-free claim.
+
+## 14. Primary Anchors
+
+- [RFC 3986: URI generic syntax](https://www.rfc-editor.org/rfc/rfc3986.html) for component boundaries, percent encoding, and dot-segment semantics.
+- [Linux `openat2(2)`](https://man7.org/linux/man-pages/man2/openat2.2.html) for descriptor-relative resolution and `RESOLVE_*` behavior.
+- [Microsoft: Naming Files, Paths, and Namespaces](https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file) for Windows naming, namespaces, reserved names, separators, and 8.3 aliases.
+- [Microsoft: `CreateFileW`](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilew) for HANDLE creation, creation dispositions, and reparse behavior.
+- [Microsoft: `GetFinalPathNameByHandleW`](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfinalpathnamebyhandlew) for inspecting the final path of an opened HANDLE.
+- [Microsoft: `GetFileInformationByHandleEx`](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfileinformationbyhandleex) for opened-object metadata classes available to the implementation.
+- [CWE-367](https://cwe.mitre.org/data/definitions/367.html) for the check-use race class and why shortening a race window is not elimination.
+- [Go: traversal-resistant file APIs](https://go.dev/blog/osroot) and [`os.Root`](https://pkg.go.dev/os#Root) for runtime root-relative operations and documented target-specific caveats.
+- [Java `SecureDirectoryStream`](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/nio/file/SecureDirectoryStream.html) for provider-dependent relative operations through an open directory stream.
+- [Python `tarfile`](https://docs.python.org/3/library/tarfile.html) and [`zipfile`](https://docs.python.org/3/library/zipfile.html) for archive entry types, metadata, sparse members, extraction-filter version changes, and caller-owned `zipfile.Path` validation.
+- [Go `archive/zip`](https://pkg.go.dev/archive/zip) for the current opt-in `zipinsecurepath` non-local-name behavior; do not treat a possible future default as current policy.