@celestia-island/hikari 0.41.5 → 0.41.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.41.5",
+  "version": "0.41.7",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/runtime/createAuthGuard.permissions.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createAuthGuard } from "./createAuthGuard";
+
+/** Shape the guard's router parameter accepts (a slim slice of
+ *  vue-router's Router — the guard only calls beforeEach/onError). */
+interface SlimRouter {
+  beforeEach: (fn: (to: GuardTo) => unknown) => void;
+  onError: (fn: (error: unknown, to: GuardTo) => void) => void;
+}
+
+interface GuardTo {
+  name?: string | symbol | null;
+  fullPath?: string;
+  meta?: Record<string, unknown>;
+}
+
+/** Minimal router double: records guards, lets tests drive them. */
+function makeRouter() {
+  const guards: Array<(to: GuardTo) => unknown> = [];
+  const router: SlimRouter = {
+    beforeEach: (fn) => { guards.push(fn); },
+    onError: () => {},
+  };
+  return {
+    router,
+    run: (to: GuardTo) => {
+      expect(guards.length).toBeGreaterThan(0);
+      return guards[guards.length - 1](to);
+    },
+  };
+}
+
+function makeAuthStore(overrides: Partial<Record<string, unknown>> = {}) {
+  return {
+    isAuthenticated: false,
+    user: null,
+    tryRestoreSession: vi.fn().mockResolvedValue(undefined),
+    checkSetup: vi.fn().mockResolvedValue({ needs_setup: false }),
+    fetchUser: vi.fn().mockResolvedValue(undefined),
+    ...overrides,
+  };
+}
+
+/** Permissions-store double mirroring the real store's semantics:
+ *  `fetch()` resolves the set and flips loaded=true; a failing fetch
+ *  leaves loaded=false (fail-open). */
+function makePermStore(init: { loaded?: boolean; perms?: string[]; failFetch?: boolean } = {}) {
+  const state = { loaded: init.loaded ?? false, perms: init.perms ?? [] };
+  return {
+    get loaded() { return state.loaded; },
+    fetch: vi.fn().mockImplementation(async () => {
+      if (init.failFetch) return;
+      state.perms = init.perms ?? [];
+      state.loaded = true;
+    }),
+    has: (perm: string) => state.perms.includes(perm),
+    hasAny: (perms: string[]) => perms.some((p) => state.perms.includes(p)),
+  };
+}
+
+const baseOpts = {
+  loginRoute: "login",
+  homeRoute: "demiurge",
+  setupRoute: "setup-redirect",
+};
+
+describe("createAuthGuard requiresPermission enforcement", () => {
+  // Contract: routes declare `requiresPermission` (e.g. /backend with
+  // "system.read") and the guard is the enforcement point. The meta used
+  // to be declared but never consumed — any authenticated user could
+  // open the admin console route and only AdminLayout's own nav filtering
+  // hid the views (field report 2026-09).
+  it("bounces a user lacking the required permission to the home route", async () => {
+    const auth = makeAuthStore({ isAuthenticated: true, user: { username: "momoi" } });
+    const perms = makePermStore({ perms: [] });
+    const { router, run } = makeRouter();
+    createAuthGuard(router, { ...baseOpts, useAuthStore: () => auth, permissions: () => perms });
+
+    const verdict = await run({
+      name: "admin",
+      fullPath: "/backend",
+      meta: { requiresAuth: true, requiresPermission: "system.read" },
+    });
+    expect(verdict).toEqual({ name: "demiurge" });
+    expect(perms.fetch).toHaveBeenCalledOnce();
+  });
+
+  it("admits a user holding the required permission", async () => {
+    const auth = makeAuthStore({ isAuthenticated: true, user: { username: "demiurge" } });
+    const perms = makePermStore({ loaded: true, perms: ["system.read"] });
+    const { router, run } = makeRouter();
+    createAuthGuard(router, { ...baseOpts, useAuthStore: () => auth, permissions: () => perms });
+
+    const verdict = await run({
+      name: "admin",
+      fullPath: "/backend",
+      meta: { requiresAuth: true, requiresPermission: "system.read" },
+    });
+    expect(verdict).toBeUndefined();
+    // Already-loaded set must not be refetched on every navigation.
+    expect(perms.fetch).not.toHaveBeenCalled();
+  });
+
+  it("accepts any-of lists via hasAny", async () => {
+    const auth = makeAuthStore({ isAuthenticated: true, user: { username: "u" } });
+    const perms = makePermStore({ loaded: true, perms: ["industrial.write"] });
+    const { router, run } = makeRouter();
+    createAuthGuard(router, { ...baseOpts, useAuthStore: () => auth, permissions: () => perms });
+
+    const verdict = await run({
+      name: "writer",
+      fullPath: "/somewhere",
+      meta: { requiresPermission: ["system.read", "industrial.write"] },
+    });
+    expect(verdict).toBeUndefined();
+  });
+
+  it("fails open while the permission set is unloaded (store outage must not brick navigation)", async () => {
+    const auth = makeAuthStore({ isAuthenticated: true, user: { username: "u" } });
+    const perms = makePermStore({ failFetch: true });
+    const { router, run } = makeRouter();
+    createAuthGuard(router, { ...baseOpts, useAuthStore: () => auth, permissions: () => perms });
+
+    const verdict = await run({
+      name: "admin",
+      fullPath: "/backend",
+      meta: { requiresAuth: true, requiresPermission: "system.read" },
+    });
+    expect(verdict).toBeUndefined();
+  });
+
+  it("ignores routes without the meta and unwired permission stores", async () => {
+    const auth = makeAuthStore({ isAuthenticated: true, user: { username: "u" } });
+    const { router, run } = makeRouter();
+    createAuthGuard(router, { ...baseOpts, useAuthStore: () => auth });
+
+    const verdict = await run({ name: "demiurge", fullPath: "/@ws", meta: { requiresAuth: true } });
+    expect(verdict).toBeUndefined();
+  });
+});

package/src/runtime/createAuthGuard.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createAuthGuard } from "./createAuthGuard";
+
+/** Shape the guard's router parameter accepts (a slim slice of
+ *  vue-router's Router — the guard only calls beforeEach/onError). */
+interface SlimRouter {
+  beforeEach: (fn: (to: GuardTo) => unknown) => void;
+  onError: (fn: (error: unknown, to: GuardTo) => void) => void;
+}
+
+interface GuardTo {
+  name?: string | symbol | null;
+  fullPath?: string;
+  meta?: Record<string, unknown>;
+}
+
+/** Minimal router double: records guards, lets tests drive them. */
+function makeRouter() {
+  const guards: Array<(to: GuardTo) => unknown> = [];
+  const router: SlimRouter = {
+    beforeEach: (fn) => { guards.push(fn); },
+    onError: () => {},
+  };
+  return {
+    router,
+    run: (to: GuardTo) => {
+      expect(guards.length).toBeGreaterThan(0);
+      return guards[guards.length - 1](to);
+    },
+  };
+}
+
+function makeAuthStore(overrides: Partial<Record<string, unknown>> = {}) {
+  return {
+    isAuthenticated: false,
+    user: null,
+    tryRestoreSession: vi.fn().mockResolvedValue(undefined),
+    checkSetup: vi.fn().mockResolvedValue({ needs_setup: false }),
+    fetchUser: vi.fn().mockResolvedValue(undefined),
+    ...overrides,
+  };
+}
+
+const baseOpts = {
+  loginRoute: "login",
+  homeRoute: "demiurge",
+  setupRoute: "setup-redirect",
+};
+
+/** The lagged-login contract: an identity fetch that fails verification
+ *  must redirect to the login route (preserving the redirect target),
+ *  never abort the navigation with an unhandled rejection — the old
+ *  behavior fed the rejection into router.onError where the lazy-load
+ *  retry handler misclassified it as a chunk failure. */
+describe("createAuthGuard identity hydration", () => {
+  it("redirects to login when the identity fetch fails verification", async () => {
+    const auth = makeAuthStore({ isAuthenticated: true });
+    // A failed verification logs out inside the real fetchUser — the
+    // guard reads the post-fetch flag, so flip it in the mock too.
+    auth.fetchUser = vi.fn().mockImplementation(async () => {
+      auth.isAuthenticated = false;
+      throw new Error("no usable identity");
+    });
+    const { router, run } = makeRouter();
+    createAuthGuard(router, { ...baseOpts, useAuthStore: () => auth });
+
+    const verdict = await run({ name: "demiurge", fullPath: "/@ws123", meta: { requiresAuth: true } });
+    expect(verdict).toEqual({ name: "login", query: { redirect: "/@ws123" } });
+    expect(auth.fetchUser).toHaveBeenCalledOnce();
+  });
+
+  it("keeps the route when the fetch fails but the session stays authenticated", async () => {
+    // Transient transport failure: the shell's own safety net retries —
+    // the guard must not bounce the user on a blip.
+    const auth = makeAuthStore({
+      isAuthenticated: true,
+      fetchUser: vi.fn().mockRejectedValue(new Error("timed out")),
+    });
+    const { router, run } = makeRouter();
+    createAuthGuard(router, { ...baseOpts, useAuthStore: () => auth });
+
+    const verdict = await run({ name: "demiurge", fullPath: "/@ws123", meta: { requiresAuth: true } });
+    expect(verdict).toBeUndefined();
+  });
+
+  it("lets a hydrated identity through without refetching", async () => {
+    const auth = makeAuthStore({
+      isAuthenticated: true,
+      user: { username: "demiurge" },
+      fetchUser: vi.fn(),
+    });
+    const { router, run } = makeRouter();
+    createAuthGuard(router, { ...baseOpts, useAuthStore: () => auth });
+
+    const verdict = await run({ name: "demiurge", fullPath: "/@ws123", meta: { requiresAuth: true } });
+    expect(verdict).toBeUndefined();
+    expect(auth.fetchUser).not.toHaveBeenCalled();
+  });
+
+  it("retries session restore after a failed attempt instead of memoizing it", async () => {
+    // Regression (user report 2026-09-07): a failed restore used to stay
+    // memoized for the SPA lifetime, so once the guard's first
+    // tryRestoreSession raced a network blip, the only way back in was a
+    // manual reload. The memo must reset on failure so the next
+    // navigation retries — with valid cookies the retry recovers.
+    const auth = makeAuthStore();
+    auth.tryRestoreSession = vi
+      .fn<() => Promise<void>>()
+      .mockImplementationOnce(async () => {
+        throw new Error("restore raced a blip");
+      })
+      .mockImplementationOnce(async () => {
+        auth.isAuthenticated = true;
+      });
+    const { router, run } = makeRouter();
+    createAuthGuard(router, { ...baseOpts, useAuthStore: () => auth });
+
+    // First navigation: restore fails → bounced to the login route.
+    const first = await run({ name: "demiurge", fullPath: "/@ws123", meta: { requiresAuth: true } });
+    expect(first).toEqual({ name: "login", query: { redirect: "/@ws123" } });
+
+    // Second navigation: the restore retries and succeeds → route passes.
+    const second = await run({ name: "demiurge", fullPath: "/@ws123", meta: { requiresAuth: true } });
+    expect(auth.tryRestoreSession).toHaveBeenCalledTimes(2);
+    expect(second).toBeUndefined();
+  });
+});

package/src/runtime/createAuthGuard.ts

@@ -0,0 +1,171 @@
+/**
+ * Shared auth route guard (family runtime).
+ *
+ * Upstreamed from shittim-chest (its copy was the most evolved form:
+ * setupWizardRoute split, permissions-store factory, session-restore
+ * retry, fetchUser failure semantics) to replace the per-repo forks —
+ * easy-hydro-erp carried an older vendored copy under
+ * `src/vendor/plana-ui/`. Structurally typed: no vue-router or pinia
+ * dependency, so hikari stays UI-library-scoped and any router-shaped
+ * object works.
+ */
+
+export interface AuthGuardOptions {
+  loginRoute: string;
+  homeRoute: string;
+  setupRoute: string;
+  /**
+   * Optional distinct wizard route that actually performs initial setup.
+   * Some apps split the flow into a redirect/landing page (`setupRoute`,
+   * e.g. locale detection) and the wizard itself (`setupWizardRoute`). When
+   * `needs_setup` is true the guard must allow BOTH, otherwise the landing
+   * page can never navigate into the wizard (infinite redirect loop).
+   */
+  setupWizardRoute?: string;
+  registerRoute?: string;
+  useAuthStore: () => {
+    isAuthenticated: boolean;
+    user: unknown;
+    tryRestoreSession: () => Promise<void>;
+    checkSetup: () => Promise<{ needs_setup: boolean; registration_enabled?: boolean }>;
+    // The guard only awaits the call — the store's `User` result is unused.
+    fetchUser: () => Promise<unknown>;
+  };
+  onLazyLoadError?: (error: Error, target: string) => void;
+  /**
+   * Permissions store factory; optional — skipped when omitted. A factory
+   * (not an instance) because pinia is installed after this module
+   * evaluates: the router is created at module scope, so an eager
+   * `usePermissionsStore()` here would run without an active pinia.
+   */
+  permissions?: () => {
+    loaded: boolean;
+    fetch: () => Promise<void>;
+    has: (perm: string) => boolean;
+    hasAny: (perms: string[]) => boolean;
+  } | undefined;
+}
+
+interface GuardRoute {
+  name?: string | symbol | null;
+  fullPath?: string;
+  meta?: Record<string, unknown>;
+}
+
+interface GuardRouter {
+  // Accepts any guard signature (vue-router's NavigationGuard takes extra
+  // args; slimmer routers take fewer) — the callback just inspects `to`.
+  // The guard callback receives the route; vue-router also passes from/next
+  // which we ignore. `never`-parameter variance keeps both sides assignable.
+  beforeEach: (fn: (to: GuardRoute, ...rest: unknown[]) => unknown) => void;
+  onError?: (fn: (error: unknown, to: GuardRoute) => void) => void;
+}
+
+export function createAuthGuard(router: GuardRouter, opts: AuthGuardOptions) {
+  let sessionRestorePromise: Promise<void> | null = null;
+  let setupChecked = false;
+
+  router.beforeEach(async (to: GuardRoute) => {
+    const auth = opts.useAuthStore();
+    const permStore = opts.permissions?.();
+
+    if (!auth.isAuthenticated) {
+      if (!sessionRestorePromise) {
+        sessionRestorePromise = auth.tryRestoreSession().catch(() => {
+          // A failed restore must not stay memoized for the SPA
+          // lifetime: the cookies may be perfectly valid and the first
+          // attempt may just have raced a network blip. Nulling here
+          // lets the next navigation (e.g. the login page's silent
+          // restore, or simply clicking another route) retry.
+          sessionRestorePromise = null;
+        });
+      }
+      await sessionRestorePromise;
+    }
+
+    if (!setupChecked && !auth.isAuthenticated) {
+      setupChecked = true;
+      try {
+        const result = await auth.checkSetup();
+        const setupAllowed = [opts.setupRoute, opts.setupWizardRoute].filter(Boolean);
+        if (result.needs_setup && !setupAllowed.includes(to.name as string)) {
+          return { name: opts.setupRoute };
+        }
+        if (!result.needs_setup && to.name === opts.setupRoute) {
+          return { name: opts.loginRoute };
+        }
+        if (
+          !result.registration_enabled &&
+          opts.registerRoute &&
+          to.name === opts.registerRoute
+        ) {
+          return { name: opts.loginRoute };
+        }
+      } catch {
+        // ignore
+      }
+    }
+
+    if (to.meta?.requiresAuth !== false && !auth.isAuthenticated) {
+      const redirect = to.fullPath && to.fullPath !== "/" ? to.fullPath : undefined;
+      return { name: opts.loginRoute, query: redirect ? { redirect } : undefined };
+    }
+
+    if (auth.isAuthenticated && permStore && !permStore.loaded) {
+      await permStore.fetch();
+    }
+
+    const publicRoutes = [opts.loginRoute, opts.setupRoute];
+    if (opts.registerRoute) publicRoutes.push(opts.registerRoute);
+    if (publicRoutes.includes(to.name as string) && auth.isAuthenticated) {
+      return "/";
+    }
+
+    if (auth.isAuthenticated && !auth.user) {
+      // Identity hydration on a session-restored client. The fetch's
+      // own failure path already clears the local session (see
+      // useAuthBase — deliberately NOT a cookie-clearing logout), so the
+      // only job here is to not let the rejection kill the navigation
+      // — an aborted guard is reported to router.onError, where it was
+      // misclassified as a lazy-load chunk failure and retried in a
+      // loop. Redirect to the login page instead; if the fetch
+      // succeeded the route renders with a real identity.
+      try {
+        await auth.fetchUser();
+      } catch {
+        if (!auth.isAuthenticated) {
+          const redirect = to.fullPath && to.fullPath !== "/" ? to.fullPath : undefined;
+          return { name: opts.loginRoute, query: redirect ? { redirect } : undefined };
+        }
+        // Transient failure while still authenticated: let the route
+        // through — the shell's own authed-watch retries hydration.
+      }
+    }
+
+    // Enforce meta-declared route permissions (`requiresPermission`). The
+    // meta has been declared since the admin console landed (/backend with
+    // "system.read") but was never consumed — AdminLayout hides its own
+    // nav for callers lacking the permission, yet the route itself rendered
+    // for ANY authenticated user (field report 2026-09: a non-admin opened
+    // the console route from the user menu and got a broken half-page).
+    // Deny only when a permission set is actually loaded; a store outage
+    // (fetch failed, loaded=false) fails open exactly like before instead
+    // of bricking navigation.
+    const required = to.meta?.requiresPermission as string | string[] | undefined;
+    if (
+      auth.isAuthenticated &&
+      permStore &&
+      required !== undefined &&
+      permStore.loaded &&
+      !(Array.isArray(required) ? permStore.hasAny(required) : permStore.has(required))
+    ) {
+      return { name: opts.homeRoute };
+    }
+  });
+
+  if (opts.onLazyLoadError) {
+    router.onError?.((error: unknown, to: GuardRoute) => {
+      opts.onLazyLoadError!(error as Error, to.fullPath ?? "");
+    });
+  }
+}

package/src/runtime/historySafetyNet.test.ts

@@ -0,0 +1,139 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { installHistorySafetyNet, sanitizeHistoryUrl } from "./historySafetyNet";
+
+/**
+ * The field bug this net closes (chest #754 lineage): some producer
+ * hands the history layer a URL that resolves off-origin — classically
+ * `origin + "undefined"` — pushState throws SecurityError, and
+ * vue-router's fallback performs a full-page location.assign onto
+ * "https://demo.dev.celestia.worldundefined/". The net must fold every
+ * off-origin / poisoned target while leaving legitimate same-origin
+ * URLs bit-for-bit untouched.
+ */
+
+describe("sanitizeHistoryUrl", () => {
+  it("passes through nullish and empty (no-op calls stay no-ops)", () => {
+    expect(sanitizeHistoryUrl(null)).toBe(null);
+    expect(sanitizeHistoryUrl(undefined)).toBe(undefined);
+    expect(sanitizeHistoryUrl("")).toBe("");
+  });
+
+  it("passes through same-origin absolute URLs untouched", () => {
+    const origin = window.location.origin;
+    expect(sanitizeHistoryUrl(`${origin}/backend#providers`)).toBe(`${origin}/backend#providers`);
+    expect(sanitizeHistoryUrl(`${origin}/@ws?box=b#think`)).toBe(`${origin}/@ws?box=b#think`);
+  });
+
+  it("passes through in-app relative targets untouched", () => {
+    expect(sanitizeHistoryUrl("/backend")).toBe("/backend");
+    expect(sanitizeHistoryUrl("/@uuid?mode=reports#think")).toBe("/@uuid?mode=reports#think");
+    expect(sanitizeHistoryUrl("#think")).toBe("#think");
+    expect(sanitizeHistoryUrl("?redirect=/backend")).toBe("?redirect=/backend");
+  });
+
+  it("folds the cross-origin concatenated-undefined class onto the fallback", () => {
+    expect(sanitizeHistoryUrl("https://demo.dev.celestia.worldundefined")).toBe("/");
+    expect(sanitizeHistoryUrl("https://demo.dev.celestia.worldundefined/")).toBe("/");
+    expect(sanitizeHistoryUrl("https://evil.example/steal")).toBe("/");
+    expect(sanitizeHistoryUrl("//evil.example/x")).toBe("/");
+  });
+
+  it("honors a custom fallback (apps whose landing route is not /)", () => {
+    expect(sanitizeHistoryUrl("https://evil.example/x", "/panel/home")).toBe("/panel/home");
+    expect(sanitizeHistoryUrl("undefined", "/panel/home")).toBe("/panel/home");
+  });
+
+  it("folds bare poisoned literals onto the fallback", () => {
+    expect(sanitizeHistoryUrl("undefined")).toBe("/");
+    expect(sanitizeHistoryUrl("null")).toBe("/");
+    expect(sanitizeHistoryUrl("NaN")).toBe("/");
+  });
+
+  it("folds unparseable garbage onto the fallback", () => {
+    expect(sanitizeHistoryUrl("http://")).toBe("/");
+  });
+});
+
+describe("installHistorySafetyNet", () => {
+  const nativePush = History.prototype.pushState;
+  const nativeReplace = History.prototype.replaceState;
+
+  afterEach(() => {
+    History.prototype.pushState = nativePush;
+    History.prototype.replaceState = nativeReplace;
+    sessionStorage.clear();
+    // The installer detects the restored (unpatched) prototype and
+    // re-patches on the next call — that self-healing path is exercised
+    // by every test after the first restore.
+  });
+
+  it("coerces a cross-origin pushState target instead of throwing", () => {
+    installHistorySafetyNet();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    expect(() => history.pushState(null, "", "https://demo.dev.celestia.worldundefined/")).not.toThrow();
+    expect(window.location.pathname).toBe("/");
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("leaves same-origin pushState untouched", () => {
+    installHistorySafetyNet();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    history.pushState(null, "", "/backend");
+    expect(window.location.pathname).toBe("/backend");
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("passes the 2-argument call shape through untouched (backStack / vue-router beforeUnload)", () => {
+    // Production shape: window.history.pushState(state, "") — no url
+    // argument at all. A wrapper-level regression that folded undefined
+    // here would break every modal/back-guard push, so pin it at the
+    // wrapper level, not just the pure function.
+    installHistorySafetyNet();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    expect(() => window.history.pushState({ marker: 1 }, "")).not.toThrow();
+    expect(window.history.state).toEqual({ marker: 1 });
+    expect(() => window.history.replaceState(null, "")).not.toThrow();
+    expect(window.history.state).toBeNull();
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("passes vue-router's real production shape (same-origin ABSOLUTE url) untouched", () => {
+    // changeLocation always composes protocol+'//'+host+base+to — pin
+    // that exact shape so an over-eager origin comparison cannot ever
+    // fold a legitimate router push.
+    installHistorySafetyNet();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const abs = `${window.location.origin}/@ws?mode=reports#think`;
+    history.pushState(null, "", abs);
+    expect(window.location.href).toBe(abs);
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("records a bounded sessionStorage evidence trail", () => {
+    installHistorySafetyNet();
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    for (let i = 0; i < 12; i++) {
+      history.replaceState(null, "", `https://evil.example/${i}`);
+    }
+    const trail = JSON.parse(sessionStorage.getItem("hikari:historyNet") || "[]") as string[];
+    expect(trail.length).toBeLessThanOrEqual(8);
+    expect(trail[trail.length - 1]).toContain("evil.example/11");
+    vi.restoreAllMocks();
+  });
+
+  it("reports through the onCoercion sink and honors evidenceKey: false", () => {
+    const seen: string[] = [];
+    installHistorySafetyNet({ evidenceKey: false, onCoercion: (info) => seen.push(info.raw) });
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    history.pushState(null, "", "https://evil.example/a");
+    history.pushState(null, "", "https://evil.example/b");
+    expect(seen).toEqual(["https://evil.example/a", "https://evil.example/b"]);
+    expect(sessionStorage.getItem("hikari:historyNet")).toBeNull();
+    vi.restoreAllMocks();
+  });
+});

package/src/runtime/historySafetyNet.ts

@@ -0,0 +1,145 @@
+/**
+ * Last-line safety net over the History API (family runtime).
+ *
+ * Upstreamed from shittim-chest #754, where the field class was first
+ * sealed app-locally: a navigation producer whose target stringifies
+ * without a leading "/" (the classic being an interpolated `undefined`)
+ * makes vue-router's HTML5 history compose `origin + base + to` into a
+ * CROSS-ORIGIN URL; the native pushState then throws a SecurityError
+ * and vue-router's catch branch performs a FULL-PAGE
+ * `location.assign(url)` onto the broken host — observed in the field
+ * as `https://<host>undefined/`. Guards ABOVE the router only protect
+ * navigations that flow through them; a stale-tab mixed module graph,
+ * a future call site, or any direct `history.pushState(garbage)` all
+ * bypass them. This net sits BELOW everything: it patches
+ * `History.prototype.pushState/replaceState` so an off-origin URL (or
+ * a bare poisoned literal, or unparseable garbage) is folded onto the
+ * app landing BEFORE the native call — with the throw gone, the
+ * full-page fallback for this class is structurally unreachable.
+ *
+ * Every coercion logs a console warning carrying the producer stack
+ * trace and appends to a bounded sessionStorage evidence trail so the
+ * next field occurrence can be attributed.
+ */
+
+/** Bare literals that read as a producer bug, never a real target. */
+const POISONED_LITERALS = new Set(["undefined", "null", "nan"]);
+
+/** sessionStorage evidence budget: keep the newest N coerced targets. */
+const EVIDENCE_MAX = 8;
+const DEFAULT_EVIDENCE_KEY = "hikari:historyNet";
+
+export interface HistorySafetyNetOptions {
+  /** Where coerced targets fold to. Must be an in-app absolute path.
+   *  Defaults to `"/"`. */
+  fallback?: string;
+  /** sessionStorage key for the evidence trail. Pass `false` to
+   *  disable persistence (the console trail always stays). */
+  evidenceKey?: string | false;
+  /** Extra sink for coercions (app telemetry, tests). */
+  onCoercion?: (info: HistoryCoercion) => void;
+}
+
+export interface HistoryCoercion {
+  method: "pushState" | "replaceState";
+  raw: string;
+  foldedTo: string;
+}
+
+/** Coerce a would-be history URL onto a safe same-origin target.
+ *
+ *  - `null`-ish / empty passes through untouched (no-ops stay no-ops);
+ *  - same-origin resolutions pass through untouched;
+ *  - anything that resolves off-origin (the `origin + "undefined"`
+ *    concatenation class, absolute foreign URLs) folds to the
+ *    fallback;
+ *  - bare poisoned literals ("undefined") fold too — as relative URLs
+ *    they would stay same-origin, but they are always producer bugs
+ *    and deserve the same hard stop.
+ */
+export function sanitizeHistoryUrl(
+  raw: string | URL | null | undefined,
+  fallback = "/",
+): string | URL | null {
+  if (raw == null || raw === "") return raw as string | URL | null;
+  const asUrl = raw instanceof URL ? raw : null;
+  const s = asUrl ? asUrl.href : String(raw);
+  const trimmed = s.trim();
+  if (POISONED_LITERALS.has(trimmed.toLowerCase())) return fallback;
+  let resolved: URL;
+  try {
+    resolved = new URL(s, window.location.href);
+  } catch {
+    return fallback;
+  }
+  return resolved.origin === window.location.origin ? (raw as string | URL) : fallback;
+}
+
+/** Marker stamped on patched methods so re-install stays a no-op while
+ *  a genuine overwrite (another lib restoring the prototype, or a test
+ *  harness) is detected and re-patched. */
+const PATCH_MARKER = "__hikariHistoryNet";
+
+/** Patch History.prototype. Safe to call multiple times: already-
+ *  patched methods are left alone, but a method overwritten back to a
+ *  foreign implementation is patched again (self-healing). */
+export function installHistorySafetyNet(options: HistorySafetyNetOptions = {}): void {
+  const fallback = options.fallback ?? "/";
+  const evidenceKey = options.evidenceKey === undefined ? DEFAULT_EVIDENCE_KEY : options.evidenceKey;
+  for (const method of ["pushState", "replaceState"] as const) {
+    const current: unknown = (History.prototype as unknown as Record<string, unknown>)[method];
+    if (
+      typeof current === "function" &&
+      (current as { [PATCH_MARKER]?: boolean })[PATCH_MARKER] === true
+    ) {
+      continue;
+    }
+    const native = current as (this: History, state: unknown, title: string, url?: string | URL | null) => unknown;
+    if (typeof native !== "function") continue;
+    const patched = function (this: History, state: unknown, title: string, url?: string | URL | null) {
+      const safe = sanitizeHistoryUrl(url, fallback);
+      if (safe !== url) {
+        const info: HistoryCoercion = { method, raw: String(url ?? ""), foldedTo: fallback };
+        reportCoercion(info, evidenceKey, options);
+      }
+      return native.call(this, state as never, title, safe as never);
+    };
+    (patched as { [PATCH_MARKER]?: boolean })[PATCH_MARKER] = true;
+    try {
+      Object.defineProperty(History.prototype, method, {
+        value: patched,
+        writable: true,
+        // Match the WebIDL shape of native prototype operations
+        // (enumerable) so Object.keys/for...in keep seeing the methods.
+        enumerable: true,
+        configurable: true,
+      });
+    } catch {
+      // Non-configurable prototype (locked-down environment) — the
+      // layers above (router guard, sanitized producers) still hold.
+    }
+  }
+}
+
+/** Log loudly and keep a bounded sessionStorage trail for attribution. */
+function reportCoercion(
+  info: HistoryCoercion,
+  evidenceKey: string | false,
+  options: HistorySafetyNetOptions,
+): void {
+  console.warn(
+    `[HistoryNet] Blocked off-origin history ${info.method} target ${JSON.stringify(info.raw)} — folded to ${JSON.stringify(info.foldedTo)}`,
+    new Error("producer stack").stack,
+  );
+  options.onCoercion?.(info);
+  if (evidenceKey === false) return;
+  const entry = `${new Date().toISOString()} ${info.method}: ${JSON.stringify(info.raw)} -> ${info.foldedTo}`;
+  try {
+    const prev = JSON.parse(sessionStorage.getItem(evidenceKey) || "[]");
+    // A corrupted/non-array payload must not kill the trail forever —
+    // start a fresh list instead of skipping every future write.
+    const list = Array.isArray(prev) ? prev : [];
+    list.push(entry);
+    sessionStorage.setItem(evidenceKey, JSON.stringify(list.slice(-EVIDENCE_MAX)));
+  } catch { /* storage unavailable — the console trail is enough */ }
+}

package/src/runtime/index.ts

@@ -3,6 +3,20 @@ export * from "./cronBus";
 export * from "./intervalBus";
 export * from "./pageLifecycle";
 export * from "./mobileViewport";
+export {
+  sanitizeHistoryUrl,
+  installHistorySafetyNet,
+  type HistorySafetyNetOptions,
+  type HistoryCoercion,
+} from "./historySafetyNet";
+export {
+  createPoisonedLocationGuard,
+  installNavigationSafetyNet,
+  type NavigationSafetyNetOptions,
+  type GuardRouter,
+  type GuardRoute,
+} from "./navigationGuard";
+export { createAuthGuard, type AuthGuardOptions } from "./createAuthGuard";
 export {
   createBackGuard,
   BACK_GUARD_MARKER,

package/src/runtime/navigationGuard.test.ts

@@ -0,0 +1,107 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  createPoisonedLocationGuard,
+  installNavigationSafetyNet,
+  type GuardRoute,
+} from "./navigationGuard";
+
+/** Minimal router double: records guards, lets tests drive them. */
+function makeRouter() {
+  const guards: Array<(to: GuardRoute) => unknown> = [];
+  const router = {
+    beforeEach: (fn: (to: GuardRoute) => unknown) => { guards.push(fn); },
+  };
+  return {
+    router,
+    run: (to: GuardRoute) => {
+      expect(guards.length).toBeGreaterThan(0);
+      return guards[guards.length - 1](to);
+    },
+  };
+}
+
+describe("createPoisonedLocationGuard", () => {
+  it("allows in-app absolute paths through", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const r = makeRouter();
+    createPoisonedLocationGuard(r.router);
+    expect(r.run({ path: "/backend", fullPath: "/backend#x" })).toBe(true);
+    expect(r.run({ path: "/@ws", fullPath: "/@ws" })).toBe(true);
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("folds non-slash-rooted paths (the stringified-undefined class)", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const r = makeRouter();
+    createPoisonedLocationGuard(r.router);
+    expect(r.run({ path: "undefined", fullPath: "undefined" })).toBe("/");
+    expect(r.run({ path: "https://evil.example/x", fullPath: "https://evil.example/x" })).toBe("/");
+    // A "//evil" PATH is not the open-redirect form once the router
+    // composes it (origin + "//evil…" = a same-origin double-slash
+    // path); the open-redirect threat lives at the location.assign
+    // layer, where safeRedirect-style producers reject it.
+    expect(r.run({ path: "//evil.example/x", fullPath: "//evil.example/x" })).toBe(true);
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("folds the bare poisoned literals but keeps deeper paths", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const r = makeRouter();
+    createPoisonedLocationGuard(r.router);
+    expect(r.run({ path: "undefined" })).toBe("/");
+    expect(r.run({ path: "null" })).toBe("/");
+    expect(r.run({ path: "nan" })).toBe("/");
+    // "/undefined" stays a valid (matched-later) in-app path — the
+    // catch-all route owns it, same contract as the chest guard.
+    expect(r.run({ path: "/undefined" })).toBe(true);
+    warn.mockRestore();
+  });
+
+  it("honors a custom fallback", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const r = makeRouter();
+    createPoisonedLocationGuard(r.router, "/panel/home");
+    expect(r.run({ path: "undefined" })).toBe("/panel/home");
+    warn.mockRestore();
+  });
+
+  it("treats a missing path as poisoned (never trust undefined)", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const r = makeRouter();
+    createPoisonedLocationGuard(r.router);
+    expect(r.run({ path: undefined as unknown as string, fullPath: "x" })).toBe("/");
+    warn.mockRestore();
+  });
+});
+
+describe("installNavigationSafetyNet", () => {
+  const nativePush = History.prototype.pushState;
+
+  afterEach(() => {
+    History.prototype.pushState = nativePush;
+    sessionStorage.clear();
+  });
+
+  it("installs both layers: history patch + router guard", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const r = makeRouter();
+    installNavigationSafetyNet({ router: r.router });
+    // Router layer folds the poisoned target before history sees it.
+    expect(r.run({ path: "undefined" })).toBe("/");
+    // History layer still coerces direct off-origin producers.
+    expect(() => history.pushState(null, "", "https://evil.example/x")).not.toThrow();
+    expect(window.location.pathname).toBe("/");
+    warn.mockRestore();
+  });
+
+  it("works without a router (history-only install)", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    expect(() => installNavigationSafetyNet({})).not.toThrow();
+    expect(() => history.pushState(null, "", "https://evil.example/y")).not.toThrow();
+    expect(window.location.pathname).toBe("/");
+    warn.mockRestore();
+  });
+});

package/src/runtime/navigationGuard.ts

@@ -0,0 +1,61 @@
+/**
+ * Poisoned-location router guard (family runtime).
+ *
+ * Companion to {@link installHistorySafetyNet}: that net folds what
+ * REACHES the history layer; this guard folds what reaches the ROUTER
+ * first, so a poisoned target dies as an in-app redirect (landing
+ * route) instead of ever composing a URL at all. Both layers share the
+ * same literal set — defense in depth, with the guard giving the nicer
+ * UX (no address-bar flicker) and the net giving the structural
+ * guarantee (covers producers that bypass the router entirely).
+ *
+ * Upstreamed from shittim-chest #622/#754.
+ */
+
+import { installHistorySafetyNet, type HistorySafetyNetOptions } from "./historySafetyNet";
+
+/** Bare literals that read as a producer bug, never a real target. */
+const POISONED_LITERALS = new Set(["undefined", "null", "nan"]);
+
+/** Structural slice of vue-router's Router — the guard only hooks
+ *  beforeEach, so any router-shaped object works (no vue-router dep:
+ *  hikari stays UI-library-scoped). */
+export interface GuardRouter {
+  beforeEach: (fn: (to: GuardRoute, ...rest: unknown[]) => unknown) => void;
+}
+
+export interface GuardRoute {
+  path?: string | null;
+  fullPath?: string;
+}
+
+export interface NavigationSafetyNetOptions extends HistorySafetyNetOptions {
+  /** Route shape the guard registers against. The History patch
+   *  installs even without a router (direct pushState producers). */
+  router?: GuardRouter;
+}
+
+/** Register the beforeEach poisoned-target fold on a router. */
+export function createPoisonedLocationGuard(
+  router: GuardRouter,
+  fallback = "/",
+): void {
+  router.beforeEach((to: GuardRoute) => {
+    const path = to.path ?? "";
+    if (!path.startsWith("/") || POISONED_LITERALS.has(path)) {
+      console.warn(
+        `[Router] Blocked poisoned navigation target "${path}" (fullPath "${to.fullPath}") — redirecting to "${fallback}"`,
+      );
+      return fallback;
+    }
+    return true;
+  });
+}
+
+/** One-call navigation safety: the History-prototype net plus the
+ *  router-level poisoned-target guard. Install before the first
+ *  navigation (module scope of the app's router setup is ideal). */
+export function installNavigationSafetyNet(options: NavigationSafetyNetOptions = {}): void {
+  installHistorySafetyNet(options);
+  if (options.router) createPoisonedLocationGuard(options.router, options.fallback ?? "/");
+}