fix(apps/ensadmin): validate name query params on name details page

.changeset/spicy-gifts-say.md

@@ -0,0 +1,5 @@
+---
+"ensadmin": patch
+---
+
+Add input validation and normalization to the Explore Names form and name detail page. The form uses `interpretNameFromUserInput` to normalize valid inputs before navigating, and shows inline errors for invalid or unsupported names. The detail page validates query params with `isNormalizedName`/`isInterpretedName` and shows appropriate error states. Empty name params show the form instead of a broken detail page.

apps/ensadmin/src/app/@breadcrumbs/name/page.tsx

@@ -19,7 +19,6 @@ export default function Page() {
   const searchParams = useSearchParams();
   const { retainCurrentRawConnectionUrlParam } = useRawConnectionUrlParam();
   const exploreNamesBaseHref = retainCurrentRawConnectionUrlParam("/name");
-
   const name = (searchParams.get("name")?.trim() || null) as Name | null;
 
   return (

apps/ensadmin/src/app/name/_components/NameDetailPageContent.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { ASSUME_IMMUTABLE_QUERY, useRecords } from "@ensnode/ensnode-react";
-import { type Name, type ResolverRecordsSelection } from "@ensnode/ensnode-sdk";
+import { type NormalizedName, type ResolverRecordsSelection } from "@ensnode/ensnode-sdk";
 
 import { Card, CardContent } from "@/components/ui/card";
 import { useActiveNamespace } from "@/hooks/active/use-active-namespace";
@@ -39,7 +39,7 @@ const AllRequestedTextRecords = [
 ];
 
 interface NameDetailPageContentProps {
-  name: Name;
+  name: NormalizedName;
 }
 
 export function NameDetailPageContent({ name }: NameDetailPageContentProps) {

apps/ensadmin/src/app/name/_components/NameErrors.tsx

@@ -0,0 +1,20 @@
+import { ErrorInfo } from "@/components/error-info";
+
+export function UnnormalizedNameError() {
+  return (
+    <section className="p-6">
+      <ErrorInfo title="Invalid Name" description="The provided name is not a valid ENS name." />
+    </section>
+  );
+}
+
+export function InterpretedNameUnsupportedError() {
+  return (
+    <section className="p-6">
+      <ErrorInfo
+        title="Encoded Labelhash Detected"
+        description="The provided name contains encoded labelhashes. Support for resolving names with encoded labelhashes is in progress and coming soon."
+      />
+    </section>
+  );
+}

apps/ensadmin/src/app/name/_components/ProfileHeader.tsx

@@ -2,14 +2,14 @@
 
 import { EnsAvatar, NameDisplay } from "@namehash/namehash-ui";
 
-import type { ENSNamespaceId, Name } from "@ensnode/ensnode-sdk";
+import type { ENSNamespaceId, NormalizedName } from "@ensnode/ensnode-sdk";
 
 import { ExternalLinkWithIcon } from "@/components/link";
 import { Card, CardContent } from "@/components/ui/card";
 import { beautifyUrl } from "@/lib/beautify-url";
 
 interface ProfileHeaderProps {
-  name: Name;
+  name: NormalizedName;
   namespaceId: ENSNamespaceId;
   headerImage?: string | null;
   websiteUrl?: string | null;

apps/ensadmin/src/app/name/page.tsx

@@ -7,8 +7,11 @@ import { type ChangeEvent, useMemo, useState } from "react";
 import { ENSNamespaceIds } from "@ensnode/datasources";
 import {
   getNamespaceSpecificValue,
+  isInterpretedName,
+  isNormalizedName,
   type Name,
   type NamespaceSpecificValue,
+  type NormalizedName,
 } from "@ensnode/ensnode-sdk";
 
 import { getNameDetailsRelativePath, NameLink } from "@/components/name-links";
@@ -17,10 +20,15 @@ import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
 import { Input } from "@/components/ui/input";
 import { useActiveNamespace } from "@/hooks/active/use-active-namespace";
 import { useRawConnectionUrlParam } from "@/hooks/use-connection-url-param";
+import {
+  interpretNameFromUserInput,
+  NameInterpretationOutcomeResult,
+} from "@/lib/interpret-name-from-user-input";
 
 import { NameDetailPageContent } from "./_components/NameDetailPageContent";
+import { InterpretedNameUnsupportedError, UnnormalizedNameError } from "./_components/NameErrors";
 
-const EXAMPLE_NAMES: NamespaceSpecificValue<string[]> = {
+const EXAMPLE_NAMES: NamespaceSpecificValue<NormalizedName[]> = {
   default: [
     "vitalik.eth",
     "gregskril.eth",
@@ -34,15 +42,15 @@ const EXAMPLE_NAMES: NamespaceSpecificValue<string[]> = {
     "lens.xyz",
     "brantly.eth",
     "lightwalker.eth",
-  ],
+  ] as NormalizedName[],
   [ENSNamespaceIds.Sepolia]: [
     "gregskril.eth",
     "vitalik.eth",
     "myens.eth",
     "recordstest.eth",
     "arrondesean.eth",
     "decode.eth",
-  ],
+  ] as NormalizedName[],
   [ENSNamespaceIds.EnsTestEnv]: [
     "alias.eth",
     "changerole.eth",
@@ -56,14 +64,15 @@ const EXAMPLE_NAMES: NamespaceSpecificValue<string[]> = {
     "sub2.parent.eth",
     "test.eth",
     "wallet.linked.parent.eth",
-  ],
+  ] as NormalizedName[],
 };
 
 export default function ExploreNamesPage() {
   const router = useRouter();
   const searchParams = useSearchParams();
-  const nameFromQuery = searchParams.get("name");
+  const nameFromQuery = searchParams.get("name") as Name | null;
   const [rawInputName, setRawInputName] = useState<Name>("");
+  const [formError, setFormError] = useState<string | null>(null);
 
   const namespace = useActiveNamespace();
   const exampleNames = useMemo(
@@ -75,23 +84,49 @@ export default function ExploreNamesPage() {
 
   const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
     e.preventDefault();
-
-    // TODO: Input validation and normalization.
-    // see: https://github.com/namehash/ensnode/issues/1140
-
-    const href = retainCurrentRawConnectionUrlParam(getNameDetailsRelativePath(rawInputName));
-
-    router.push(href);
+    setFormError(null);
+
+    const result = interpretNameFromUserInput(rawInputName);
+
+    switch (result.outcome) {
+      case NameInterpretationOutcomeResult.Empty:
+        break;
+      case NameInterpretationOutcomeResult.Normalized: {
+        const href = retainCurrentRawConnectionUrlParam(
+          getNameDetailsRelativePath(result.interpretation),
+        );
+        router.push(href);
+        break;
+      }
+      case NameInterpretationOutcomeResult.Reencoded:
+        setFormError(
+          "The provided input contains encoded labelhashes. Support for resolving names with encoded labelhashes is in progress and coming soon.",
+        );
+        break;
+      case NameInterpretationOutcomeResult.Encoded:
+        setFormError("The provided input is not a valid ENS name.");
+        break;
+    }
   };
 
   const handleRawInputNameChange = (e: ChangeEvent<HTMLInputElement>) => {
     e.preventDefault();
-
+    setFormError(null);
     setRawInputName(e.target.value);
   };
 
-  if (nameFromQuery) {
-    return <NameDetailPageContent name={nameFromQuery} />;
+  // Detail page: validate name from query params using only validation checks (no normalization).
+  // see: https://github.com/namehash/ensnode/issues/1140
+  if (nameFromQuery !== null && nameFromQuery !== "") {
+    if (isNormalizedName(nameFromQuery)) {
+      return <NameDetailPageContent name={nameFromQuery} />;
+    }
+
+    if (isInterpretedName(nameFromQuery)) {
+      return <InterpretedNameUnsupportedError />;
+    }
+
+    return <UnnormalizedNameError />;
   }
 
   return (
@@ -115,12 +150,13 @@ export default function ExploreNamesPage() {
               />
               <Button
                 type="submit"
-                disabled={rawInputName.length === 0}
+                disabled={rawInputName.trim().length === 0}
                 className="max-sm:self-stretch"
               >
                 View Profile
               </Button>
             </fieldset>
+            {formError && <p className="text-sm text-red-600">{formError}</p>}
           </form>
           <div className="flex flex-col gap-2 justify-center">
             <p className="text-sm font-medium leading-none">Examples:</p>

apps/ensadmin/src/lib/interpret-name-from-user-input.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  interpretNameFromUserInput,
+  NameInterpretationOutcomeResult,
+} from "./interpret-name-from-user-input";
+
+describe("interpretNameFromUserInput", () => {
+  describe("Empty outcome", () => {
+    it("returns Empty for empty string", () => {
+      const result = interpretNameFromUserInput("");
+      expect(result.outcome).toBe(NameInterpretationOutcomeResult.Empty);
+      expect(result.interpretation).toBe("");
+    });
+
+    it("returns Empty for whitespace-only string", () => {
+      const result = interpretNameFromUserInput("   ");
+      expect(result.outcome).toBe(NameInterpretationOutcomeResult.Empty);
+      expect(result.interpretation).toBe("");
+    });
+
+    it("returns Empty for tab/newline whitespace", () => {
+      const result = interpretNameFromUserInput("\t\n");
+      expect(result.outcome).toBe(NameInterpretationOutcomeResult.Empty);
+      expect(result.interpretation).toBe("");
+    });
+  });
+
+  describe("Normalized outcome", () => {
+    it("returns Normalized for already-normalized name", () => {
+      const result = interpretNameFromUserInput("vitalik.eth");
+      expect(result.outcome).toBe(NameInterpretationOutcomeResult.Normalized);
+      expect(result.interpretation).toBe("vitalik.eth");
+    });
+
+    it("normalizes uppercase to lowercase", () => {
+      const result = interpretNameFromUserInput("VITALIK.ETH");
+      expect(result.outcome).toBe(NameInterpretationOutcomeResult.Normalized);
+      expect(result.interpretation).toBe("vitalik.eth");
+    });
+
+    it("normalizes mixed case", () => {
+      const result = interpretNameFromUserInput("LiGhTWaLkEr.EtH");
+      expect(result.outcome).toBe(NameInterpretationOutcomeResult.Normalized);
+      expect(result.interpretation).toBe("lightwalker.eth");
+    });
+
+    it("preserves inputName in result", () => {
+      const result = interpretNameFromUserInput("VITALIK.ETH");
+      expect(result.inputName).toBe("VITALIK.ETH");
+    });
+
+    it("handles single-label name", () => {
+      const result = interpretNameFromUserInput("eth");
+      expect(result.outcome).toBe(NameInterpretationOutcomeResult.Normalized);
+      expect(result.interpretation).toBe("eth");
+    });
+  });
+
+  describe("Reencoded outcome", () => {
+    it("returns Reencoded for encoded labelhash input", () => {
+      const result = interpretNameFromUserInput(
+        "[e4310bf4547cb18b16b5348881d24a66d61fa94a013e5636b730b86ee64a3923].eth",
+      );
+      expect(result.outcome).toBe(NameInterpretationOutcomeResult.Reencoded);
+      expect(result.interpretation).toBe(
+        "[e4310bf4547cb18b16b5348881d24a66d61fa94a013e5636b730b86ee64a3923].eth",
+      );
+    });
+
+    it("lowercases encoded labelhash hex", () => {
+      const result = interpretNameFromUserInput(
+        "[E4310BF4547CB18B16B5348881D24A66D61FA94A013E5636B730B86EE64A3923].eth",
+      );
+      expect(result.outcome).toBe(NameInterpretationOutcomeResult.Reencoded);
+      expect(result.interpretation).toBe(
+        "[e4310bf4547cb18b16b5348881d24a66d61fa94a013e5636b730b86ee64a3923].eth",
+      );
+    });
+
+    it("handles multiple encoded labelhash labels", () => {
+      const result = interpretNameFromUserInput(
+        "[e4310bf4547cb18b16b5348881d24a66d61fa94a013e5636b730b86ee64a3923].[4f5b812789fc606be1b3b16908db13fc7a9adf7ca72641f84d75b47069d3d7f0]",
+      );
+      expect(result.outcome).toBe(NameInterpretationOutcomeResult.Reencoded);
+    });
+  });
+
+  describe("Encoded outcome", () => {
+    it("returns Encoded for invalid characters", () => {
+      const result = interpretNameFromUserInput("abc|123.eth");
+      expect(result.outcome).toBe(NameInterpretationOutcomeResult.Encoded);
+      // The unnormalizable label gets encoded as a labelhash
+      expect(result.interpretation).toMatch(/^\[.{64}\]\.eth$/);
+    });
+
+    it("returns Encoded for empty labels (consecutive dots)", () => {
+      const result = interpretNameFromUserInput("abc..123");
+      expect(result.outcome).toBe(NameInterpretationOutcomeResult.Encoded);
+      if (result.outcome === NameInterpretationOutcomeResult.Encoded) {
+        expect(result.hadEmptyLabels).toBe(true);
+      }
+    });
+
+    it("returns Encoded for single dot", () => {
+      const result = interpretNameFromUserInput(".");
+      expect(result.outcome).toBe(NameInterpretationOutcomeResult.Encoded);
+      if (result.outcome === NameInterpretationOutcomeResult.Encoded) {
+        expect(result.hadEmptyLabels).toBe(true);
+      }
+    });
+
+    it("returns Encoded for space (non-trimmed, non-empty)", () => {
+      // " " trims to "" so this is Empty, but "a b" has a space inside a label
+      const result = interpretNameFromUserInput("a b.eth");
+      expect(result.outcome).toBe(NameInterpretationOutcomeResult.Encoded);
+    });
+
+    it("preserves inputName in Encoded result", () => {
+      const result = interpretNameFromUserInput("abc|123.eth");
+      expect(result.inputName).toBe("abc|123.eth");
+    });
+
+    it("hadEmptyLabels is false when no empty labels", () => {
+      const result = interpretNameFromUserInput("abc|123.eth");
+      if (result.outcome === NameInterpretationOutcomeResult.Encoded) {
+        expect(result.hadEmptyLabels).toBe(false);
+      }
+    });
+  });
+
+  describe("mixed label scenarios", () => {
+    it("normalizable + encoded labelhash = Reencoded", () => {
+      const result = interpretNameFromUserInput(
+        "VITALIK.[e4310bf4547cb18b16b5348881d24a66d61fa94a013e5636b730b86ee64a3923]",
+      );
+      expect(result.outcome).toBe(NameInterpretationOutcomeResult.Reencoded);
+      expect(result.interpretation.startsWith("vitalik.")).toBe(true);
+    });
+
+    it("unnormalizable takes priority over reencoded", () => {
+      const result = interpretNameFromUserInput(
+        "abc|123.[e4310bf4547cb18b16b5348881d24a66d61fa94a013e5636b730b86ee64a3923]",
+      );
+      expect(result.outcome).toBe(NameInterpretationOutcomeResult.Encoded);
+    });
+
+    it("always produces a valid interpretation string", () => {
+      const inputs = [
+        "vitalik.eth",
+        "VITALIK.ETH",
+        "abc|123.eth",
+        "abc..123",
+        ".",
+        "[e4310bf4547cb18b16b5348881d24a66d61fa94a013e5636b730b86ee64a3923].eth",
+      ];
+      for (const input of inputs) {
+        const result = interpretNameFromUserInput(input);
+        expect(typeof result.interpretation).toBe("string");
+        expect(result.interpretation.length).toBeGreaterThan(0);
+      }
+    });
+  });
+});