perf: skip canonicalization via h3's isCanonicalPath fast path

[pi0x]

Important

Draft — blocked on h3 releasing isCanonicalPath (h3js/h3#1460, stacked on h3js/h3#1458). Peer/dev pins are set to the anticipated ^2.0.1-rc.26; CI cannot install until it ships. Local verification below ran against a pnpm linked build of that branch.

What

For the common already-canonical pathname, the matcher and isPathInScope paid four per-request string scans proving canonicalization is a no-op (resolveDotSegments' internal guard ×3 + the SEPARATOR_RUN_RE collapse). This adds an isTriviallyCanonical fast path: h3's new isCanonicalPath(pathname, { decodeSlashes: true, mergeSlashes: true }) in strict mode implies both alternate readings are no-ops (canonicalPath identity and mergedCanonicalPath === undefined), so one h3-owned scan skips them entirely — for the runtime matcher, compiled matchers (createMatcherFromFind is shared), and isPathInScope.

No decode knowledge is duplicated in this package — that's the point of upstreaming the predicate: a stale local prescan would silently skip a canonicalization step (an auth/scope bypass, not a perf bug).

Safety chain

• h3 pins isCanonicalPath(p, o) ⇔ resolveDotSegments(p, o) === p (200k-assertion property test in h3's suite).
• test/scope.test.ts pins the derivation layered on top: strict-mode canonical ⇒ canonicalPath(p) === p and mergedCanonicalPath(p) === undefined (seeded fuzz, both directions), plus directed accept/reject cases.
• New invariant documented in .agents/SECURITY.md.
• All existing security regression suites (scope, dual-path union, encoded-separator hardening) pass unchanged; 367 tests green against the linked h3 branch.

Numbers

Compiled basicAuth matcher (mitata, node 24, x64), identical results on the adversarial path matrix:

request	before	after
normal (non-matching, canonical)	183 ns	109 ns (210 ns on h3 rc.25 → ~2× total)
matching /admin/panel	563 ns	530 ns

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7215d667-4497-49b1-ae9f-7e8707465a17

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch perf/trivially-canonical-fast-path

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pi0]

landed on main