@zudojs/http 1.2.0 → 1.3.0

package/dist/httpRequest/http.request.js

@@ -1,5 +1,7 @@
 import { HTTP_HEADERS } from "../httpConstants/http.constants.js";
 import { InvalidJSONError } from "../httpErrors/httpError.helper.js";
+import { parseQueryString as parseHardenedQueryString } from "../httpQuery/queryParse/index.js";
+import { getClientIp, isTrustedPeer, } from "../httpTrustProxy/httpTrustProxy.helper.js";
 /* -------------------------------------------------------------------------- */
 /* Request Headers                                                            */
 /* -------------------------------------------------------------------------- */
@@ -72,7 +74,8 @@ export class NodeHTTPRequest {
     cachedJSON;
     jsonParsed = false;
     constructor(request, options = {}) {
-        const protocol = getRequestProtocol(request);
+        const trustProxy = options.trustProxy ?? false;
+        const protocol = getRequestProtocol(request, trustProxy);
         const host = getRequestHost(request);
         const path = getRequestPath(request);
         this.method = normalizeHTTPMethod(request.method);
@@ -84,9 +87,9 @@ export class NodeHTTPRequest {
         this.params = options.params ?? {};
         this.protocol = protocol;
         this.hostname = getHostname(host);
-        this.ip = options.ip ?? getRequestIP(request);
+        this.ip = options.ip ?? getRequestIP(request, trustProxy);
         this.ips = options.ips;
-        this.secure = protocol === "https" || protocol === "wss";
+        this.secure = protocol === "https";
         this.rawBody = options.rawBody;
         this.body = options.body;
         this.signal = options.signal;
@@ -229,10 +232,41 @@ export function getHostname(host) {
 /* -------------------------------------------------------------------------- */
 /* Protocol                                                                   */
 /* -------------------------------------------------------------------------- */
-export function getRequestProtocol(request) {
-    const forwarded = request.headers[HTTP_HEADERS.X_FORWARDED_PROTO];
-    if (typeof forwarded === "string") {
-        return (forwarded.split(",", 1)[0] ?? "").trim().toLowerCase();
+/** The only schemes a forwarded proto may name. */
+const FORWARDED_PROTOCOLS = Object.freeze(["http", "https"]);
+/**
+ * Presents an `IncomingMessage` in the shape `httpTrustProxy` works on, so
+ * this path and the Node adapter share one implementation of the hop logic.
+ */
+function toProxyRequest(request) {
+    return {
+        headers: request.headers,
+        socket: { remoteAddress: request.socket?.remoteAddress },
+    };
+}
+/**
+ * Resolves the scheme the client used.
+ *
+ * `X-Forwarded-Proto` is written by whoever opened the socket, so it is read
+ * only when that peer is a configured trusted proxy, and only when it names
+ * `http` or `https` — a value such as `wss` is discarded rather than
+ * propagated. With the default `trustProxy` of `false` the socket's own TLS
+ * state is the only input.
+ *
+ * @param request - The incoming Node request.
+ * @param trustProxy - Which peers may speak through `X-Forwarded-Proto`.
+ * @returns `"https"` or `"http"`.
+ */
+export function getRequestProtocol(request, trustProxy = false) {
+    if (isTrustedPeer(toProxyRequest(request), trustProxy)) {
+        const forwarded = request.headers[HTTP_HEADERS.X_FORWARDED_PROTO];
+        const value = Array.isArray(forwarded) ? forwarded[0] : forwarded;
+        if (typeof value === "string") {
+            const proto = (value.split(",", 1)[0] ?? "").trim().toLowerCase();
+            if (FORWARDED_PROTOCOLS.includes(proto)) {
+                return proto;
+            }
+        }
     }
     if ("encrypted" in request.socket &&
         request.socket.encrypted) {
@@ -243,43 +277,60 @@ export function getRequestProtocol(request) {
 /* -------------------------------------------------------------------------- */
 /* IP                                                                         */
 /* -------------------------------------------------------------------------- */
-export function getRequestIP(request) {
-    const forwarded = request.headers[HTTP_HEADERS.X_FORWARDED_FOR];
-    if (typeof forwarded === "string") {
-        const first = forwarded.split(",", 1)[0]?.trim();
-        if (first) {
-            return first;
-        }
+/**
+ * Resolves the client address.
+ *
+ * The socket peer is authoritative. `X-Forwarded-For` is consulted only when
+ * that peer is a configured trusted proxy, and the chain walk is delegated to
+ * `getClientIp` so there is a single implementation of the hop logic. With
+ * the default `trustProxy` of `false` the peer address is returned unchanged,
+ * which is what an allowlist, per-IP rate limit or audit trail keyed on
+ * `req.ip` needs.
+ *
+ * @param request - The incoming Node request.
+ * @param trustProxy - Which peers may speak through `X-Forwarded-For`.
+ * @returns The client address, or `undefined` when the socket has none.
+ */
+export function getRequestIP(request, trustProxy = false) {
+    const proxyRequest = toProxyRequest(request);
+    const peer = proxyRequest.socket?.remoteAddress;
+    if (!isTrustedPeer(proxyRequest, trustProxy)) {
+        return peer ?? undefined;
     }
-    return request.socket.remoteAddress ?? undefined;
+    return getClientIp(proxyRequest, trustProxy) ?? peer ?? undefined;
 }
 /* -------------------------------------------------------------------------- */
 /* Query                                                                      */
 /* -------------------------------------------------------------------------- */
+/**
+ * Parses the query component of a request-target into a flat record.
+ *
+ * Delegates to the hardened `httpQuery` parser, the same one behind the Node
+ * adapter's `request.query` and the router's `ctx.query`. This function used
+ * to carry its own loop that accumulated into an object literal and read
+ * `result[key]` without an own-property check, which had two consequences on
+ * fully attacker-controlled input:
+ *
+ * - `?__proto__=a&__proto__=b` assigned an array through the `__proto__`
+ *   setter, so the returned query object's prototype became that array. The
+ *   parameter vanished from its own keys while the object silently gained
+ *   `length`, `map` and the rest of `Array.prototype`.
+ * - `?constructor=x` read the inherited `Object` constructor as the "existing"
+ *   value and stored it in the result, handing a handler
+ *   `query.constructor === [Function: Object], "x"]`.
+ *
+ * It also applied none of the four documented query limits, so a request with
+ * 50,000 parameters was parsed in full. Delegating fixes all three, and makes
+ * a limit breach throw {@link HTTPQueryLimitError} (414) as it already did on
+ * every other request path.
+ */
 export function parseQueryString(url) {
     const queryIndex = url.indexOf("?");
     if (queryIndex < 0) {
-        return {};
-    }
-    const queryString = url.slice(queryIndex + 1);
-    if (!queryString) {
-        return {};
-    }
-    const searchParams = new URLSearchParams(queryString);
-    const result = {};
-    for (const [key, value] of searchParams.entries()) {
-        const existing = result[key];
-        if (existing === undefined) {
-            result[key] = value;
-            continue;
-        }
-        if (Array.isArray(existing)) {
-            result[key] = [...existing, value];
-            continue;
-        }
-        result[key] = [existing, value];
+        return parseHardenedQueryString(undefined);
     }
-    return result;
+    const hashIndex = url.indexOf("#", queryIndex + 1);
+    return parseHardenedQueryString(url.slice(queryIndex + 1, hashIndex === -1 ? undefined : hashIndex));
 }
 /* -------------------------------------------------------------------------- */
 /* Method                                                                     */

package/dist/httpRequest/httpRequest.context.js

@@ -7,6 +7,7 @@
  * The context is intentionally framework-agnostic so adapters can populate it
  * from Node.js, Bun, Deno, or another HTTP runtime.
  */
+import { AsyncLocalStorage } from "node:async_hooks";
 import { parseRequestTarget } from "./target/httpRequest.target.js";
 /* -------------------------------------------------------------------------- */
 /* Constants                                                                  */
@@ -378,24 +379,16 @@ function validateHeaderValue(value) {
         throw new TypeError("HTTP header value cannot contain CR or LF characters.");
     }
 }
+/**
+ * Builds the request-context store.
+ *
+ * `AsyncLocalStorage` used to be reached through `globalThis.require`, which
+ * does not exist in ESM under Node. The `typeof` guard turned that into a
+ * silent `undefined`, so `runWithRequestContext` merely called its callback
+ * and `getCurrentRequestContext` always returned `undefined`. It is imported
+ * statically now, as the rest of the package imports its Node built-ins.
+ */
 function createAsyncContextStorage() {
-    /*
-     * AsyncLocalStorage is intentionally loaded lazily so the HTTP package
-     * remains usable in browser and non-Node runtimes.
-     */
-    try {
-        const runtimeRequire = globalThis.require;
-        if (typeof runtimeRequire !== "function") {
-            return undefined;
-        }
-        const asyncHooks = runtimeRequire("node:async_hooks");
-        if (!asyncHooks.AsyncLocalStorage) {
-            return undefined;
-        }
-        return new asyncHooks.AsyncLocalStorage();
-    }
-    catch {
-        return undefined;
-    }
+    return new AsyncLocalStorage();
 }
 //# sourceMappingURL=httpRequest.context.js.map

package/dist/httpRequest/target/httpRequest.target.d.ts

@@ -17,8 +17,8 @@
 /**
  * Parses a request-target (origin-form, absolute-form or `*`) into a URL.
  *
- * An origin-form target is never parsed as an authority. Unparseable input
- * yields the root URL.
+ * An origin-form target is never parsed as an authority, and repeated slashes
+ * in the path are collapsed. Unparseable input yields the root URL.
  */
 export declare function parseRequestTarget(target: string): URL;
 /**

package/dist/httpRequest/target/httpRequest.target.js

@@ -17,21 +17,39 @@
 const TARGET_BASE = "http://zudojs.invalid";
 const ABSOLUTE_FORM = /^https?:\/\//i;
 const ENCODED_DOT = /%2e/gi;
+const REPEATED_SLASH = /\/{2,}/g;
+/**
+ * Collapses repeated slashes in a parsed target's path.
+ *
+ * The router normalises `/{2,}` away before matching, while the request
+ * context kept them, so `//admin/secret` dispatched to the route registered
+ * at `/admin/secret` while a guard reading `request.path` saw a path that did
+ * not start with `/admin/`. Both sides parse here, so collapsing once here
+ * keeps them in agreement. The query and fragment are untouched.
+ */
+function collapsePathSlashes(url) {
+    if (!url.pathname.includes("//")) {
+        return url;
+    }
+    const collapsed = new URL(url.href);
+    collapsed.pathname = url.pathname.replace(REPEATED_SLASH, "/");
+    return collapsed;
+}
 /**
  * Parses a request-target (origin-form, absolute-form or `*`) into a URL.
  *
- * An origin-form target is never parsed as an authority. Unparseable input
- * yields the root URL.
+ * An origin-form target is never parsed as an authority, and repeated slashes
+ * in the path are collapsed. Unparseable input yields the root URL.
  */
 export function parseRequestTarget(target) {
     try {
         if (target.startsWith("/")) {
-            return new URL(`${TARGET_BASE}${target}`);
+            return collapsePathSlashes(new URL(`${TARGET_BASE}${target}`));
         }
         if (ABSOLUTE_FORM.test(target)) {
-            return new URL(target);
+            return collapsePathSlashes(new URL(target));
         }
-        return new URL(`${TARGET_BASE}/${target === "*" ? "" : target}`);
+        return collapsePathSlashes(new URL(`${TARGET_BASE}/${target === "*" ? "" : target}`));
     }
     catch {
         return new URL(`${TARGET_BASE}/`);

package/dist/httpRouter/core/factory/httpRoute.factory.base.d.ts

@@ -9,7 +9,18 @@ import { type HttpResponseContext as ResponseContext } from "../../../httpRespon
 export declare function normalizeMethod(method: string): HttpMethod | "*";
 export declare function normalizeMethods(method: HttpMethod | readonly HttpMethod[] | "*"): readonly (HttpMethod | "*")[];
 export declare function isHttpMethod(value: string): value is HttpMethod;
-export declare function collectAllowedMethods(routes: readonly CompiledRoute[], path: string): HttpMethod[];
+/**
+ * Collects the methods registered for a path.
+ *
+ * @param routes - The compiled routes to consider.
+ * @param path - The request path.
+ * @param caseSensitive - The router's case sensitivity. This used to be
+ *   hardcoded to `false`, so a case-sensitive router advertised `Allow`
+ *   methods belonging to a route that only differed by case — a method the
+ *   client would then get a 404 from, and a disclosure of the other route.
+ * @returns The allowed methods, with `HEAD` implied by `GET`.
+ */
+export declare function collectAllowedMethods(routes: readonly CompiledRoute[], path: string, caseSensitive?: boolean): HttpMethod[];
 /**
  * Extracts the monotonic registration sequence from a generated route id.
  *
@@ -39,6 +50,12 @@ export declare function defaultNotFoundHandler(context: HttpRouterRequestContext
 export declare function defaultMethodNotAllowedHandler(context: HttpRouterRequestContext, allowedMethods: readonly HttpMethod[]): ResponseContext;
 /**
  * Runs a matched route's middleware chain followed by its handler.
+ *
+ * Every result is folded into the ambient response context
+ * (`context.middleware.response`), which is the object route middleware
+ * writes to. Returning the handler's brand new response instead — as this
+ * used to — silently discarded every header, cookie and status a route
+ * middleware had set before calling `next()`.
  */
 export declare function executeRoute(route: MatchedRoute, context: HttpRouterContext): Promise<ResponseContext>;
 //# sourceMappingURL=httpRoute.factory.base.d.ts.map

package/dist/httpRouter/core/factory/httpRoute.factory.base.js

@@ -36,10 +36,21 @@ export function isHttpMethod(value) {
         value === "CONNECT" ||
         value === "TRACE");
 }
-export function collectAllowedMethods(routes, path) {
+/**
+ * Collects the methods registered for a path.
+ *
+ * @param routes - The compiled routes to consider.
+ * @param path - The request path.
+ * @param caseSensitive - The router's case sensitivity. This used to be
+ *   hardcoded to `false`, so a case-sensitive router advertised `Allow`
+ *   methods belonging to a route that only differed by case — a method the
+ *   client would then get a 404 from, and a disclosure of the other route.
+ * @returns The allowed methods, with `HEAD` implied by `GET`.
+ */
+export function collectAllowedMethods(routes, path, caseSensitive = false) {
     const methods = new Set();
     for (const route of routes) {
-        if (!matchCompiledRoute(route, path, false)) {
+        if (!matchCompiledRoute(route, path, caseSensitive)) {
             continue;
         }
         if (isHttpMethod(route.definition.method)) {
@@ -153,11 +164,43 @@ export function defaultMethodNotAllowedHandler(context, allowedMethods) {
 /* -------------------------------------------------------------------------- */
 /* Route Execution                                                            */
 /* -------------------------------------------------------------------------- */
+/**
+ * Merges one response context into another.
+ *
+ * Status, status text, headers, cookies, metadata and body are all carried
+ * over, so nothing a handler produced is lost.
+ *
+ * @param target - The response that stays authoritative.
+ * @param source - The response to fold into it.
+ * @returns The target response.
+ */
+function mergeRouteResponse(target, source) {
+    if (source === target) {
+        return target;
+    }
+    target.setStatus(source.status, source.statusText);
+    target.headers_obj(source.headers);
+    for (const cookie of source.cookies) {
+        target.setCookie(cookie);
+    }
+    for (const [key, value] of Object.entries(source.metadata)) {
+        target.setMetadata(key, value);
+    }
+    target.setBody(source.body);
+    return target;
+}
 /**
  * Runs a matched route's middleware chain followed by its handler.
+ *
+ * Every result is folded into the ambient response context
+ * (`context.middleware.response`), which is the object route middleware
+ * writes to. Returning the handler's brand new response instead — as this
+ * used to — silently discarded every header, cookie and status a route
+ * middleware had set before calling `next()`.
  */
 export async function executeRoute(route, context) {
     const layers = route.middleware;
+    const ambient = context.middleware.response;
     let invoked = -1;
     const run = async (index) => {
         if (index <= invoked) {
@@ -166,7 +209,7 @@ export async function executeRoute(route, context) {
         invoked = index;
         const layer = layers[index];
         if (layer === undefined) {
-            return normalizeResponse(await route.handler(context));
+            return mergeRouteResponse(ambient, await normalizeResponse(await route.handler(context)));
         }
         let downstream;
         const result = await layer(context.middleware, async () => {
@@ -174,12 +217,12 @@ export async function executeRoute(route, context) {
             return downstream;
         });
         if (result instanceof HttpResponseContext) {
-            return result;
+            return mergeRouteResponse(ambient, result);
         }
         if (typeof Response !== "undefined" && result instanceof Response) {
-            return normalizeResponse(result);
+            return mergeRouteResponse(ambient, await normalizeResponse(result));
         }
-        return downstream ?? context.middleware.response;
+        return downstream ?? ambient;
     };
     return run(0);
 }

package/dist/httpRouter/core/factory/httpRoute.factory.js

@@ -4,7 +4,7 @@
 import { HttpRouter } from "../register/httpRouter.register.js";
 import { HttpRouterGroup } from "../group/httpRouterGroup.core.js";
 import { RouteConflictError, InvalidRoutePatternError, } from "../error/httpRouter.error.js";
-import { normalizePath } from "../util/httpRoute.util.js";
+import { normalizeRoutePattern } from "../util/httpRoute.util.js";
 /**
  * Creates a new HTTP router instance.
  */
@@ -17,7 +17,7 @@ export function createRouter(options = {}) {
 export function createRoute(definition) {
     return {
         ...definition,
-        path: normalizePath(definition.path),
+        path: normalizeRoutePattern(definition.path),
         middleware: Object.freeze([...(definition.middleware ?? [])]),
         metadata: Object.freeze({ ...(definition.metadata ?? {}) }),
     };
@@ -26,7 +26,7 @@ export function createRoute(definition) {
  * Builds a route path from a pattern and parameters.
  */
 export function buildRoutePath(pattern, params = {}) {
-    const normalized = normalizePath(pattern);
+    const normalized = normalizeRoutePattern(pattern);
     return normalized
         .replace(/:([a-zA-Z_][a-zA-Z0-9_-]*)(\?)?/g, (_match, name, optional) => {
         const value = params[name];

package/dist/httpRouter/core/register/httpRouter.register.js

@@ -4,9 +4,9 @@
 import { HttpRouterError, RouteConflictError, } from "../error/httpRouter.error.js";
 import { HttpRouterGroup } from "../group/httpRouterGroup.core.js";
 import { collectAllowedMethods, createFallbackRoute, createOptionsResponse, defaultMethodNotAllowedHandler, defaultNotFoundHandler, executeRoute, extractRouteSequence, isHttpMethod, normalizeMethod, normalizeMethods, normalizeResponse, } from "../factory/httpRoute.factory.base.js";
-import { getRequestMethod, getRequestSignal, getRequestUrl, normalizePath, parseQuery, parseUrl, } from "../util/httpRoute.util.js";
+import { getRequestMethod, getRequestSignal, getRequestUrl, normalizeMatchPath, normalizePath, normalizeRoutePattern, parseQuery, parseUrl, } from "../util/httpRoute.util.js";
 import { matchCompiledRoute } from "../../matching/httpRoute.matcher.core.js";
-import { compileRoute } from "../../pattern/httpRoute.pattern.parse.js";
+import { compareSegmentSpecificity, compileRoute, } from "../../pattern/httpRoute.pattern.parse.js";
 import { createRouterMiddlewareContext } from "../../httpRouter.context.js";
 export class HttpRouter {
     routes = [];
@@ -90,7 +90,7 @@ export class HttpRouter {
     remove(method, path) {
         const normalizedMethod = normalizeMethod(method);
         const index = this.routes.findIndex((route) => route.definition.method === normalizedMethod &&
-            route.definition.path === normalizePath(path));
+            route.definition.path === normalizeRoutePattern(path));
         if (index === -1) {
             return false;
         }
@@ -122,11 +122,13 @@ export class HttpRouter {
     match(method, path) {
         const normalizedMethod = method.toUpperCase();
         const normalizedPath = normalizePath(path);
+        const matchPath = normalizeMatchPath(path);
         const candidates = this.sortedRoutes();
+        const allowedForPath = () => collectAllowedMethods(candidates, matchPath, this.routerOptions.caseSensitive);
         const allowed = new Set();
         let pathMatched = false;
         for (const route of candidates) {
-            const params = matchCompiledRoute(route, normalizedPath, this.routerOptions.caseSensitive);
+            const params = matchCompiledRoute(route, matchPath, this.routerOptions.caseSensitive);
             if (!params) {
                 continue;
             }
@@ -137,9 +139,7 @@ export class HttpRouter {
                     matched: true,
                     route: route.definition,
                     params,
-                    allowedMethods: Object.freeze([
-                        ...collectAllowedMethods(candidates, normalizedPath),
-                    ]),
+                    allowedMethods: Object.freeze([...allowedForPath()]),
                     path: normalizedPath,
                     method: normalizedMethod,
                 };
@@ -153,16 +153,13 @@ export class HttpRouter {
                 if (route.definition.method !== "GET") {
                     continue;
                 }
-                const params = matchCompiledRoute(route, normalizedPath, this.routerOptions.caseSensitive);
+                const params = matchCompiledRoute(route, matchPath, this.routerOptions.caseSensitive);
                 if (params) {
                     return {
                         matched: true,
                         route: route.definition,
                         params,
-                        allowedMethods: Object.freeze([
-                            ...collectAllowedMethods(candidates, normalizedPath),
-                            "HEAD",
-                        ]),
+                        allowedMethods: Object.freeze([...allowedForPath(), "HEAD"]),
                         path: normalizedPath,
                         method: normalizedMethod,
                     };
@@ -176,10 +173,7 @@ export class HttpRouter {
                 matched: true,
                 route: undefined,
                 params: {},
-                allowedMethods: Object.freeze([
-                    ...collectAllowedMethods(candidates, normalizedPath),
-                    "OPTIONS",
-                ]),
+                allowedMethods: Object.freeze([...allowedForPath(), "OPTIONS"]),
                 path: normalizedPath,
                 method: normalizedMethod,
             };
@@ -261,11 +255,11 @@ export class HttpRouter {
     /* ------------------------------------------------------------------------ */
     register(method, path, handler, options) {
         const normalizedMethod = normalizeMethod(method);
-        const normalizedPath = normalizePath(path);
+        const normalizedPath = normalizeRoutePattern(path);
         if (typeof handler !== "function") {
             throw new HttpRouterError("Route handler must be a function.");
         }
-        const compiled = compileRoute(normalizedPath, this.routerOptions.strictTrailingSlash ||
+        const compiled = compileRoute(path, this.routerOptions.strictTrailingSlash ||
             options.strictTrailingSlash === true);
         const existing = this.routes.find((route) => route.definition.method === normalizedMethod &&
             route.definition.path === normalizedPath);
@@ -290,6 +284,7 @@ export class HttpRouter {
             segments: compiled.segments,
             score: compiled.score,
             strictTrailingSlash: compiled.strictTrailingSlash,
+            expectsTrailingSlash: compiled.expectsTrailingSlash,
         });
         return () => {
             this.remove(normalizedMethod, normalizedPath);
@@ -297,9 +292,9 @@ export class HttpRouter {
     }
     sortedRoutes() {
         return [...this.routes].sort((left, right) => {
-            const score = right.score - left.score;
-            if (score !== 0) {
-                return score;
+            const specificity = compareSegmentSpecificity(left.segments, right.segments);
+            if (specificity !== 0) {
+                return specificity;
             }
             return (extractRouteSequence(left.definition.id) -
                 extractRouteSequence(right.definition.id));

package/dist/httpRouter/core/types/httpRouter.type.d.ts

@@ -104,6 +104,12 @@ export interface CompiledRoute {
     readonly segments: readonly CompiledSegment[];
     readonly score: number;
     readonly strictTrailingSlash: boolean;
+    /**
+     * Whether the registered pattern ended with a slash.
+     *
+     * Only consulted when {@link CompiledRoute.strictTrailingSlash} is set.
+     */
+    readonly expectsTrailingSlash?: boolean;
 }
 export { HttpRouterError, RouteConflictError, } from "../error/httpRouter.error.js";
 //# sourceMappingURL=httpRouter.type.d.ts.map

package/dist/httpRouter/core/util/httpRoute.util.d.ts

@@ -24,8 +24,55 @@ export declare function parseUrl(value: string): URL;
  * for the same parameter.
  */
 export declare function parseQuery(params: URLSearchParams): Readonly<Record<string, string | string[]>>;
+/**
+ * Normalizes a **request** path.
+ *
+ * Strips the query string, forces a leading slash, collapses repeated
+ * slashes, and trims a trailing slash.
+ *
+ * This must not be used on a route *pattern*: a pattern may legitimately
+ * contain `?` (the optional-parameter marker), which this function treats as
+ * the start of a query string. Use {@link normalizeRoutePattern} for
+ * patterns.
+ */
 export declare function normalizePath(path: string): string;
+/**
+ * Normalizes a request path while preserving a single trailing slash.
+ *
+ * The trailing slash is the only information a strict-trailing-slash route
+ * needs and {@link normalizePath} destroys it, so matching runs on this
+ * spelling instead.
+ *
+ * @param path - The raw request path, possibly with a query or fragment.
+ * @returns The normalized path, keeping one trailing slash if present.
+ */
+export declare function normalizeMatchPath(path: string): string;
+/**
+ * Normalizes a route **pattern**.
+ *
+ * Identical to {@link normalizePath} except that `?` is left alone, so the
+ * documented optional-parameter syntax (`/users/:id?`, `/files/{name?}`)
+ * survives registration.
+ *
+ * @param pattern - The raw route pattern.
+ * @returns The normalized pattern.
+ */
+export declare function normalizeRoutePattern(pattern: string): string;
+/**
+ * Reports whether a path carries a meaningful trailing slash.
+ *
+ * @param path - The path to inspect.
+ * @returns `true` when the path ends with `/` and is not the root path.
+ */
+export declare function hasTrailingSlash(path: string): boolean;
 export declare function splitPath(path: string): string[];
+/**
+ * Splits a route pattern into its segments, keeping `?` markers intact.
+ *
+ * @param pattern - The raw route pattern.
+ * @returns The pattern's non-empty segments.
+ */
+export declare function splitRoutePattern(pattern: string): string[];
 export declare function validateParameterName(name: string, path: string): void;
 export declare function decodeRouteValue(value: string): string;
 /**