Summary

• Moves resolveDotSegments out of src/utils/internal/path.ts into a new public src/utils/path.ts, exported from src/index.ts (serveStatic already used it internally to resolve ./.. and encoded dot segments before touching disk).
• Adds an opt-in decodeSlashes option that also collapses encoded path separators into real / boundaries — off by default, since decoding a path separator changes segment count and therefore which route matches, not just security scope.
• Decoding of the three path-special escapes (%2e, %2f, %5c) is pessimistic: nested %25-encodings (%252f, %25252f, …) collapse too, so a downstream that decodes any number of times cannot smuggle a separator or dot segment past a scope check. All other escapes (%20, %C3%A9, …) are never decoded.
• serveStatic behavior is unchanged for normal request paths; a few hostile/edge inputs are now hardened (in the fail-closed direction) and can produce a different computed asset id: backslash-only paths (/a\b → /a/b), extra leading separators (//foo → /foo), and multi-encoded dot segments now resolve as traversal instead of passing through opaquely. Also drops a now-redundant withLeadingSlash wrapper in serveStatic.

Why

Downstream tools that do their own prefix/scope matching against event.url.pathname (e.g. nitro's route-rules, which independently matches rules like /secure/** against a path and needs to guard against an encoded separator like %2f bypassing a narrower rule that a downstream proxy target/redirect would later decode) need the exact same ./.. resolution + encoded-dot-segment handling h3 already has and battle-tested for serveStatic. There was previously no way to reuse it since it lived under utils/internal/, so nitro had to reimplement the same tricky, security-sensitive logic from scratch (nitrojs/nitro#4396). This exports the single hardened implementation so it can be reused directly instead of re-derived per consumer.

%2f decoding stays opt-in and separate from routing/dispatch: it must never be baked into event.url.pathname globally, since some apps intentionally rely on %2F to keep an id containing a literal slash as one opaque path segment (e.g. /files/:id). The decodeSlashes option lets a caller ask for the "canonical path a downstream will eventually see" purely for an out-of-band scope check, without affecting what h3 itself routes on.

Nested %25-encodings are collapsed (rather than decoding strictly once) because a strict single-level decode makes the scope-check use case unsound: /allowed/..%252f..%252fadmin would look safely under /allowed while a downstream that decodes twice sees /admin. Since decodeSlashes exists precisely to anticipate downstream decodes, the resolver handles arbitrary decode depth itself instead of pushing a fixpoint loop onto every security-sensitive caller.

Test plan

• pnpm test — full suite (lint + typecheck + coverage) passes, src/utils/path.ts at 100% coverage
• test/unit/path.test.ts covers: plain paths, literal ./.., root-clamping, %2e decoding, backslash normalization, default opaque %2f/%5c, the decodeSlashes option (including traversal revealed only after decoding separators), and nested %25-encoded separators/dots at multiple depths
• Updated test/unit/package.test.ts export snapshot

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added a new public path utility resolveDotSegments to safely normalize ./.., normalize backslashes, and decode percent-encoded dot segments.
  • Added decodeSlashes option to also decode percent-encoded path separators when needed.
• Bug Fixes
  • Improved static file URL handling by resolving dot segments after URL decoding, preventing traversal above / and avoiding protocol-relative outputs.
• Documentation
  • Documented resolveDotSegments and decodeSlashes in the security utilities guide.
• Tests
  • Expanded unit tests for normalization, encoded edge cases, and clamping/traversal hardening.