@tschk/moonshine-router 0.3.7 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tschk/moonshine-router",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "description": "Renderer-neutral route graph and matcher with optional React navigation",
   "license": "ISC",
   "type": "module",

package/src/index.ts

@@ -19,6 +19,7 @@ export {
   useNavigate,
   useRouter,
   MoonshineRouter,
+  isExternal,
   Link,
   safeHref,
 } from "./navigation.js";

package/src/navigation.ts

@@ -6,7 +6,6 @@ import {
   useEffect,
   useMemo,
   useRef,
-  useState,
   useSyncExternalStore,
   type ReactNode,
 } from "react";
@@ -180,9 +179,6 @@ export function MoonshineRouter(props: MoonshineRouterProps): ReactNode {
   // Routes are matched on the pathname alone; the query rides along in the
   // signal only so that changing it re-renders.
   const pathname = splitLocation(props.path ?? browserPath)[0];
-  const [ready, setReady] = useState(
-    typeof window === "undefined" || props.path !== undefined,
-  );
 
   // Compiling every pattern is a sizeable share of this component's render, and
   // the result depends only on the route list.
@@ -203,7 +199,6 @@ export function MoonshineRouter(props: MoonshineRouterProps): ReactNode {
     activeRouter = runtime;
     if (props.path === undefined) {
       runtime.syncFromBrowser();
-      setReady(true);
       const onPop = () => runtime.syncFromBrowser();
       window.addEventListener("popstate", onPop);
       return () => {
@@ -224,10 +219,6 @@ export function MoonshineRouter(props: MoonshineRouterProps): ReactNode {
     runtime,
   };
 
-  if (!ready && props.path === undefined && typeof window !== "undefined") {
-    // Avoid hydration flicker on first client paint before popstate sync
-  }
-
   return createElement(
     RouterContext.Provider,
     { value },
@@ -265,21 +256,54 @@ export function safeHref(href: string): string {
 }
 
 /** Anchor that uses client-side navigation. */
+/**
+ * Whether the browser should keep its own handling of `href`.
+ *
+ * A client router may only intercept a same-document navigation. Anything
+ * carrying a scheme (`https:`, `mailto:`, `tel:`), a protocol-relative `//host`,
+ * a bare fragment, or an explicit non-`_self` target belongs to the browser: it
+ * opens a mail client, a new tab, or another origin, none of which this router
+ * can do.
+ *
+ * `safeHref` deliberately allows those schemes through — it only strips ones
+ * that could execute. Allowing a scheme is not the same as claiming to handle
+ * it, and conflating the two is how `<Link href="https://github.com/me">` came
+ * to push `/me` onto the app's own origin: preventDefault ran, `navigate`
+ * rebuilt the URL against `window.location.origin`, and the user landed on a
+ * 404 instead of GitHub.
+ *
+ * Exported so the host adapters share one definition rather than each carrying
+ * a copy — three of them already did, byte for byte, and the copy this module
+ * lacked is exactly the one that was wrong.
+ */
+export function isExternal(href: string, target?: string): boolean {
+  if (target && target !== "_self") return true;
+  return (
+    /^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(href) ||
+    href.startsWith("//") ||
+    href.startsWith("#")
+  );
+}
+
 export function Link(props: {
   href: string;
   children?: ReactNode;
   className?: string;
   replace?: boolean;
+  target?: string;
 }): ReactNode {
   const nav = useNavigate();
   const href = safeHref(props.href);
+  const external = isExternal(href, props.target);
   return createElement(
     "a",
     {
       href,
       className: props.className,
+      target: props.target,
       onClick: (event: MouseEvent) => {
         if (
+          external ||
           event.defaultPrevented ||
           event.button !== 0 ||
           event.metaKey ||

package/src/pattern.ts

@@ -75,64 +75,113 @@ export function compilePattern(pattern: string): CompiledPattern {
     normalized = "/";
   }
 
-  const match = (pathname: string): MatchResult | null => {
-    const pathParts = splitPath(pathname);
-    const params: RouteParams = {};
-    const score: number[] = [];
-    let i = 0;
-
-    for (const segment of segments) {
-      if (segment.kind === "rest") {
-        const remaining = pathParts.slice(i).join("/");
-        try {
-          params[segment.name] = decodeURIComponent(remaining);
-        } catch {
-          return null;
-        }
-        score.push(SEGMENT_PRECEDENCE.rest);
-        i = pathParts.length;
-        continue;
+  let pathParts: string[] = [];
+
+  /**
+   * Decodes the tail a `*rest` segment captures.
+   *
+   * Per part, not on the joined string. Decoding after the join lets an encoded
+   * separator smuggle structure past the router: `/files/%2e%2e%2fsecret` used
+   * to arrive as `path: "../secret"`, and a handler doing the obvious
+   * `join(dir, params.path)` then read outside its directory. `a%2Fb` and `a/b`
+   * were likewise indistinguishable. Same rules the static server already
+   * applies in `resolveStaticPath`, so the two agree about what a path segment
+   * may contain.
+   */
+  const decodeRest = (parts: readonly string[]): string | null => {
+    const decoded: string[] = [];
+    for (const part of parts) {
+      const d = decodePart(part);
+      if (
+        d === null ||
+        d === "." ||
+        d === ".." ||
+        d.includes("\0") ||
+        d.includes("/")
+      ) {
+        return null;
       }
+      decoded.push(d);
+    }
+    return decoded.join("/");
+  };
 
-      if (segment.kind === "static") {
-        const part = pathParts[i];
-        if (part === undefined) return null;
-        const decoded = decodePart(part);
-        if (decoded === null) return null;
-        if (decoded !== segment.value) return null;
-        score.push(SEGMENT_PRECEDENCE.static);
-        i++;
-        continue;
-      }
+  /**
+   * Matches `segments` from `si` against `pathParts` from `pi`.
+   *
+   * Recursive because an optional segment has to be able to give its part back.
+   * The old linear pass consumed a part whenever one was present, so
+   * `/:lang?/about` matched `/en/about` and then failed `/about` — the i18n
+   * prefix route 404ing on its own default locale, silently, because a failed
+   * match is indistinguishable from no route. Consuming is tried first so the
+   * greedy reading still wins where both work.
+   */
+  const matchFrom = (si: number, pi: number): MatchResult | null => {
+    if (si === segments.length) {
+      return pi === pathParts.length ? { params: {}, score: [] } : null;
+    }
 
-      if (segment.kind === "dynamic") {
-        const part = pathParts[i];
-        if (part === undefined) return null;
-        const decoded = decodePart(part);
-        if (decoded === null) return null;
-        params[segment.name] = decoded;
-        score.push(SEGMENT_PRECEDENCE.dynamic);
-        i++;
-        continue;
-      }
+    const segment = segments[si];
+    const part = pathParts[pi];
+
+    const withHead = (
+      rest: MatchResult,
+      points: number,
+      binding?: [string, string],
+    ): MatchResult => ({
+      params: binding
+        ? { [binding[0]]: binding[1], ...rest.params }
+        : rest.params,
+      score: [points, ...rest.score],
+    });
+
+    if (segment.kind === "rest") {
+      const value = decodeRest(pathParts.slice(pi));
+      if (value === null) return null;
+      const rest = matchFrom(si + 1, pathParts.length);
+      return (
+        rest && withHead(rest, SEGMENT_PRECEDENCE.rest, [segment.name, value])
+      );
+    }
 
-      if (segment.kind === "optional") {
-        const part = pathParts[i];
-        if (part === undefined) {
-          score.push(0);
-          continue;
-        }
-        const decoded = decodePart(part);
-        if (decoded === null) return null;
-        params[segment.name] = decoded;
-        score.push(SEGMENT_PRECEDENCE.optional);
-        i++;
-        continue;
+    if (segment.kind === "static") {
+      if (part === undefined) return null;
+      const decoded = decodePart(part);
+      if (decoded === null || decoded !== segment.value) return null;
+      const rest = matchFrom(si + 1, pi + 1);
+      return rest && withHead(rest, SEGMENT_PRECEDENCE.static);
+    }
+
+    if (segment.kind === "dynamic") {
+      if (part === undefined) return null;
+      const decoded = decodePart(part);
+      if (decoded === null) return null;
+      const rest = matchFrom(si + 1, pi + 1);
+      return (
+        rest &&
+        withHead(rest, SEGMENT_PRECEDENCE.dynamic, [segment.name, decoded])
+      );
+    }
+
+    // optional: consume first, then fall back to skipping.
+    if (part !== undefined) {
+      const decoded = decodePart(part);
+      if (decoded !== null) {
+        const rest = matchFrom(si + 1, pi + 1);
+        if (rest)
+          return withHead(rest, SEGMENT_PRECEDENCE.optional, [
+            segment.name,
+            decoded,
+          ]);
       }
     }
+    const skipped = matchFrom(si + 1, pi);
+    return skipped && withHead(skipped, 0);
+  };
 
-    if (i < pathParts.length) return null;
-    return { params, score };
+  const match = (pathname: string): MatchResult | null => {
+    pathParts = splitPath(pathname);
+    return matchFrom(0, 0);
   };
 
   return { pattern, segments, precedence, normalized, match };

package/test/dom.ts

@@ -0,0 +1,109 @@
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import type { ReactNode } from "react";
+
+/**
+ * `bun test` shares one process across files, so registering happy-dom leaks
+ * its browser implementations into every other suite: its `Request` strips
+ * forbidden headers like `Cookie`, and its streams are not the ones SSR
+ * renderers write to. Keep the DOM, put Bun's platform globals back.
+ */
+const keepNative = [
+  "Request",
+  "Response",
+  "Headers",
+  "fetch",
+  "ReadableStream",
+  "WritableStream",
+  "TransformStream",
+  "TextEncoder",
+  "TextDecoder",
+  "AbortController",
+  "AbortSignal",
+  "Blob",
+  "FormData",
+  "URL",
+  "URLSearchParams",
+  "setTimeout",
+  "clearTimeout",
+  "setInterval",
+  "clearInterval",
+  "queueMicrotask",
+] as const;
+
+if (!("happyDOM" in globalThis)) {
+  const scope = globalThis as unknown as Record<string, unknown>;
+  const native = Object.fromEntries(keepNative.map((key) => [key, scope[key]]));
+  GlobalRegistrator.register({ url: "https://example.com/start" });
+  Object.assign(scope, native);
+}
+
+(
+  globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+const mounted: { unmount(): void }[] = [];
+
+/** Mounts `element` into a fresh detached container and flushes effects. */
+export async function render(element: ReactNode): Promise<HTMLElement> {
+  const container = document.createElement("div");
+  document.body.append(container);
+  const root = createRoot(container);
+  mounted.push(root);
+  await act(async () => {
+    root.render(element);
+  });
+  return container;
+}
+
+/**
+ * Unmounts every root from the current test. Without this, trees left
+ * subscribed to the router signal re-render on the next test's navigation.
+ */
+export async function cleanup(): Promise<void> {
+  await act(async () => {
+    for (const root of mounted.splice(0)) root.unmount();
+  });
+  document.body.replaceChildren();
+}
+
+/**
+ * Dispatches a real bubbling click so React's root listener runs, and reports
+ * whether the handler claimed the event.
+ *
+ * A document-level guard records `defaultPrevented` and then cancels the event
+ * regardless, so happy-dom does not follow un-intercepted anchors and leave the
+ * document on a URL later tests cannot navigate from.
+ */
+export async function click(
+  node: Element,
+  init: MouseEventInit = {},
+): Promise<{ defaultPrevented: boolean }> {
+  let defaultPrevented = false;
+  const guard = (event: Event): void => {
+    defaultPrevented = event.defaultPrevented;
+    event.preventDefault();
+  };
+  document.addEventListener("click", guard);
+  try {
+    await act(async () => {
+      node.dispatchEvent(
+        new MouseEvent("click", {
+          bubbles: true,
+          cancelable: true,
+          button: 0,
+          ...init,
+        }),
+      );
+    });
+  } finally {
+    document.removeEventListener("click", guard);
+  }
+  return { defaultPrevented };
+}
+
+/** Resets the document location between navigation assertions. */
+export function setLocation(url: string): void {
+  window.history.replaceState({}, "", new URL(url, "https://example.com").href);
+}

package/test/link.test.tsx

@@ -1,7 +1,8 @@
-import { describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { createElement } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
-import { Link, safeHref } from "../src/navigation";
+import { isExternal, Link, safeHref } from "../src/navigation";
+import { click, render, setLocation, cleanup } from "./dom";
 
 function hrefOf(href: string): string {
   const html = renderToStaticMarkup(createElement(Link, { href }, "go"));
@@ -36,3 +37,58 @@ describe("Link", () => {
     expect(hrefOf("/ok")).toBe("/ok");
   });
 });
+
+describe("isExternal", () => {
+  test("a scheme, a protocol-relative host, a fragment or a target is the browser's", () => {
+    expect(isExternal("https://github.com/me")).toBe(true);
+    expect(isExternal("mailto:me@example.com")).toBe(true);
+    expect(isExternal("tel:+15551234")).toBe(true);
+    expect(isExternal("//cdn.example.com/x")).toBe(true);
+    expect(isExternal("#section")).toBe(true);
+    expect(isExternal("/about", "_blank")).toBe(true);
+  });
+
+  test("a same-document path is the router's", () => {
+    expect(isExternal("/about")).toBe(false);
+    expect(isExternal("/about", "_self")).toBe(false);
+    expect(isExternal("/a?b=1")).toBe(false);
+  });
+});
+
+describe("Link and external targets", () => {
+  // The regression: safeHref *allows* https/mailto/tel — it only strips schemes
+  // that could execute — and Link took that as permission to intercept them.
+  // preventDefault ran, navigate rebuilt the URL against the current origin, and
+  // `https://github.com/me` became a push to `/me` on this app. The href looked
+  // correct the whole time, so it only surfaced as a 404 on click.
+  afterEach(cleanup);
+  beforeEach(() => setLocation("/start"));
+
+  async function clicked(href: string, target?: string) {
+    const container = await render(createElement(Link, { href, target }, "go"));
+    const node = container.querySelector("a");
+    if (!node) throw new Error("Link did not render an anchor");
+    return click(node);
+  }
+
+  test("leaves an external URL to the browser", async () => {
+    expect((await clicked("https://github.com/me")).defaultPrevented).toBe(
+      false,
+    );
+  });
+
+  test("leaves mailto and tel to the browser", async () => {
+    expect((await clicked("mailto:me@example.com")).defaultPrevented).toBe(
+      false,
+    );
+    expect((await clicked("tel:+15551234")).defaultPrevented).toBe(false);
+  });
+
+  test("leaves an explicit target to the browser", async () => {
+    expect((await clicked("/about", "_blank")).defaultPrevented).toBe(false);
+  });
+
+  test("still intercepts a same-document path", async () => {
+    expect((await clicked("/about")).defaultPrevented).toBe(true);
+  });
+});

package/test/navigation.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from "bun:test";
+import { splitLocation, safeHref, isExternal } from "../src/navigation";
+
+describe("splitLocation", () => {
+  test("splits path and query", () => {
+    expect(splitLocation("/path?query=1")).toEqual(["/path", "query=1"]);
+  });
+  test("handles no query string", () => {
+    expect(splitLocation("/path")).toEqual(["/path", ""]);
+  });
+  test("handles empty string", () => {
+    expect(splitLocation("")).toEqual(["", ""]);
+  });
+  test("handles query string only", () => {
+    expect(splitLocation("?query=1")).toEqual(["", "query=1"]);
+  });
+  test("handles multiple question marks by splitting on the first", () => {
+    expect(splitLocation("/path?query=1?other=2")).toEqual([
+      "/path",
+      "query=1?other=2",
+    ]);
+  });
+});
+
+describe("safeHref", () => {
+  test("allows safe schemes", () => {
+    expect(safeHref("http://example.com")).toBe("http://example.com");
+    expect(safeHref("https://example.com")).toBe("https://example.com");
+    expect(safeHref("mailto:user@example.com")).toBe("mailto:user@example.com");
+    expect(safeHref("tel:+1234567890")).toBe("tel:+1234567890");
+    expect(safeHref("ftp://example.com")).toBe("ftp://example.com");
+  });
+  test("allows relative paths", () => {
+    expect(safeHref("/path")).toBe("/path");
+    expect(safeHref("?query=1")).toBe("?query=1");
+    expect(safeHref("#hash")).toBe("#hash");
+    expect(safeHref("path")).toBe("path");
+  });
+  test("rewrites unsafe schemes to #", () => {
+    expect(safeHref("javascript:alert(1)")).toBe("#");
+    expect(safeHref("vbscript:msgbox(1)")).toBe("#");
+    expect(safeHref("data:text/html,<h1>hello</h1>")).toBe("#");
+  });
+  test("strips control characters to prevent evasion", () => {
+    expect(safeHref("java\x09script:alert(1)")).toBe("#");
+    expect(safeHref("java\nscript:alert(1)")).toBe("#");
+  });
+  test("handles empty string and spaces", () => {
+    expect(safeHref("")).toBe("#");
+    expect(safeHref("   ")).toBe("#");
+  });
+});
+
+describe("isExternal", () => {
+  test("identifies scheme-bearing URLs as external", () => {
+    expect(isExternal("http://example.com")).toBe(true);
+    expect(isExternal("https://example.com")).toBe(true);
+    expect(isExternal("mailto:test@test.com")).toBe(true);
+  });
+  test("identifies protocol-relative URLs as external", () => {
+    expect(isExternal("//example.com")).toBe(true);
+  });
+  test("identifies hash-only URLs as external (browser handles them)", () => {
+    expect(isExternal("#section")).toBe(true);
+  });
+  test("identifies target other than _self as external", () => {
+    expect(isExternal("/path", "_blank")).toBe(true);
+    expect(isExternal("/path", "_parent")).toBe(true);
+  });
+  test("identifies same-document relative paths as internal", () => {
+    expect(isExternal("/path")).toBe(false);
+    expect(isExternal("path")).toBe(false);
+    expect(isExternal("/path?query=1")).toBe(false);
+    expect(isExternal("/path", "_self")).toBe(false);
+  });
+});

package/test/pattern.test.ts

@@ -56,3 +56,59 @@ describe("matchPath", () => {
     expect(matchPath("/a/b", "/a")).toBeNull();
   });
 });
+
+describe("optional segments backtrack", () => {
+  // The regression: the matcher consumed a part whenever one was present and
+  // never gave it back, so `/:lang?/about` matched `/en/about` and then failed
+  // `/about` — an i18n prefix route 404ing on its own default locale. A failed
+  // match is indistinguishable from no route, so it surfaced as a bare 404.
+  test("matches with the optional segment absent", () => {
+    expect(matchPath("/:lang?/about", "/about")?.params).toEqual({});
+  });
+
+  test("still binds the optional segment when it is present", () => {
+    expect(matchPath("/:lang?/about", "/en/about")?.params).toEqual({
+      lang: "en",
+    });
+  });
+
+  test("does not match when the rest of the pattern cannot", () => {
+    expect(matchPath("/:lang?/about", "/en/contact")).toBeNull();
+    expect(matchPath("/:lang?/about", "/a/b/about")).toBeNull();
+  });
+
+  test("handles two optionals before a static tail", () => {
+    expect(matchPath("/:a?/:b?/end", "/end")?.params).toEqual({});
+    expect(matchPath("/:a?/:b?/end", "/x/end")?.params).toEqual({ a: "x" });
+    expect(matchPath("/:a?/:b?/end", "/x/y/end")?.params).toEqual({
+      a: "x",
+      b: "y",
+    });
+  });
+});
+
+describe("rest segments decode per part", () => {
+  // Decoding the joined string let an encoded separator smuggle structure past
+  // the router: a handler doing `join(dir, params.path)` on the result read
+  // outside its directory, and `a%2Fb` was indistinguishable from `a/b`.
+  test("rejects an encoded traversal", () => {
+    expect(matchPath("/files/*path", "/files/%2e%2e%2fsecret")).toBeNull();
+    expect(matchPath("/files/*path", "/files/..%2Fsecret")).toBeNull();
+  });
+
+  test("rejects an encoded separator", () => {
+    expect(matchPath("/files/*path", "/files/a%2Fb")).toBeNull();
+  });
+
+  test("still captures an ordinary nested path", () => {
+    expect(matchPath("/files/*path", "/files/a/b/c.txt")?.params).toEqual({
+      path: "a/b/c.txt",
+    });
+  });
+
+  test("still decodes ordinary escapes within a part", () => {
+    expect(matchPath("/files/*path", "/files/my%20file.txt")?.params).toEqual({
+      path: "my file.txt",
+    });
+  });
+});