fix: validate avatar route boundary and thread branded input types

Close the second unvalidated boundary and make validation enforceable by
the compiler across the whole resolver call graph.

- Validate the GET /:type/:id avatar route inside parseQuery: the stripped,
  lowercased id must be a valid address or handle (avatarIdSchema), else the
  route returns HTTP 400 (InvalidQueryError) instead of a 500. The /clear
  route gets the same 400 path. Size/width/height query clamping is unchanged.
- Add branded nominal types in src/helpers/validation.ts: addressSchema /
  handleSchema now .brand() and export ValidatedAddress / ValidatedHandle, and
  avatarIdSchema (ValidatedAddress | ValidatedHandle) for the avatar route. All
  entry-point schemas (JSON-RPC + avatar route) output branded values.
- Thread the branded input types through the resolver entry points:
  lookupAddresses / resolveNames, lookupDomains, getOwner, and the avatar
  resolver entries (resolvers/ens, resolvers/basename, addressResolvers
  basename getAvatar / castToEnsName). The compiler now enforces that only
  validated values reach the resolvers. Plain Address / Handle aliases stay for
  values flowing OUT of the resolvers (resolved network values are plain).
- Drop the now-redundant inner isAddress guard in lookupDomains (shape is
  guaranteed by the branded Address at the only caller).
- Keep normalizeAddresses: its getAddress checksum / lowercase step is
  NORMALIZATION (required for stable redis cache keys and dedup), not
  validation, and its reject-filter still guards the unbranded clearCache
  route param. Cache key shape is unchanged. The batch cap (max 50) stays as a
  zod .max at the boundary since types cannot encode array length.
- Tests: add e2e cases asserting a bad avatar id returns 400 and valid
  address / handle ids do not; brand integration test inputs via the real
  schemas (test/helpers/validation.ts); convert the two lookupDomains
  invalid-input tests to assert the boundary schema rejects them.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tony8713

src/addressResolvers/basename.ts

@@ -4,6 +4,7 @@ import { namehash } from '@ethersproject/hash';
 import { capture } from '@snapshot-labs/snapshot-sentry';
 import snapshot from '@snapshot-labs/snapshot.js';
 import { FetchError, provider as getProvider, isEvmAddress, isSilencedError } from './utils';
+import { addressSchema, AvatarId } from '../helpers/validation';
 import { Address, EMPTY_ADDRESS, getUrl, Handle } from '../utils';
 
 export const NAME = 'Basename';
@@ -69,9 +70,12 @@ export async function resolveNames(handles: Handle[]): Promise<Record<Handle, Ad
 
 // Avatar text record, used by the avatar resolver. Resolves the name against
 // Base specifically, so an address' ENS primary name can't shadow its Basename.
-export async function getAvatar(nameOrAddress: string): Promise<string | null> {
-  const name = isEvmAddress(nameOrAddress)
-    ? (await lookupAddresses([nameOrAddress]))[nameOrAddress]
+export async function getAvatar(nameOrAddress: AvatarId): Promise<string | null> {
+  // Re-derive the Address brand from the already validated id: when it is an
+  // address, reverse-resolve to a Basename; otherwise treat it as a handle.
+  const asAddress = addressSchema.safeParse(nameOrAddress);
+  const name = asAddress.success
+    ? (await lookupAddresses([asAddress.data]))[asAddress.data]
     : normalizeBasename(nameOrAddress);
 
   return name ? getUrl(await call('text', [namehash(name), 'avatar'])) : null;

src/addressResolvers/index.ts

@@ -15,6 +15,7 @@ import {
   withoutEmptyValues
 } from './utils';
 import { timeAddressResolverResponse as timeResponse } from '../helpers/metrics';
+import { ValidatedAddress, ValidatedHandle } from '../helpers/validation';
 import { Address, Handle } from '../utils';
 
 const RESOLVERS = [
@@ -70,7 +71,9 @@ async function _call(fnName: string, input: string[], maxInputLength: number) {
   );
 }
 
-export async function lookupAddresses(addresses: Address[]): Promise<Record<Address, Handle>> {
+export async function lookupAddresses(
+  addresses: ValidatedAddress[]
+): Promise<Record<Address, Handle>> {
   const result = await _call(
     'lookupAddresses',
     Array.from(new Set(normalizeAddresses(addresses))),
@@ -80,7 +83,7 @@ export async function lookupAddresses(addresses: Address[]): Promise<Record<Addr
   return mapOriginalInput(addresses, result);
 }
 
-export async function resolveNames(handles: Handle[]): Promise<Record<Handle, Address>> {
+export async function resolveNames(handles: ValidatedHandle[]): Promise<Record<Handle, Address>> {
   const result = await _call(
     'resolveNames',
     Array.from(new Set(normalizeHandles(handles))),

src/addressResolvers/utils.ts

@@ -29,7 +29,17 @@ export function withoutEmptyAddress(obj: Record<string, any>) {
   return Object.fromEntries(Object.entries(obj).filter(([key]) => key !== EMPTY_ADDRESS));
 }
 
-export function normalizeAddresses(addresses: Address[]): Address[] {
+// NORMALIZATION, not validation. getAddress() checksums EVM addresses and
+// Starknet addresses are lowercased so the redis cache keys and the dedup Set
+// in src/addressResolvers/index.ts are stable regardless of input casing. This
+// step MUST stay even though the branded Address type already guarantees shape
+// at the JSON-RPC boundary.
+//
+// It also still drops anything getAddress() rejects: the clearCache path
+// (src/api.ts /clear/address/:id) reaches here with a raw, unbranded route
+// param, so this thin reject is the boundary guard for that one path. The
+// other callers pass branded Address[] for which the filter is a no-op.
+export function normalizeAddresses(addresses: string[]): Address[] {
   return addresses
     .map(a => {
       if (isStarknetAddress(a)) {
@@ -42,8 +52,8 @@ export function normalizeAddresses(addresses: Address[]): Address[] {
     .filter(a => a) as Address[];
 }
 
-export function normalizeHandles(handles: Handle[]): Handle[] {
-  return handles.filter(h => /^[^\s]*\.[^\s]*$/.test(h)).map(h => h.toLowerCase());
+export function normalizeHandles(handles: string[]): Handle[] {
+  return handles.filter(h => /^[^\s]*\.[^\s]*$/.test(h)).map(h => h.toLowerCase()) as Handle[];
 }
 
 export function isSilencedError(error: any, additionalMessages?: string[]): boolean {

src/api.ts

@@ -14,7 +14,14 @@ import {
 } from './helpers/validation';
 import lookupDomains from './lookupDomains';
 import resolvers from './resolvers';
-import { getCacheKey, parseQuery, resize, ResolverType, setHeader } from './utils';
+import {
+  getCacheKey,
+  InvalidQueryError,
+  parseQuery,
+  resize,
+  ResolverType,
+  setHeader
+} from './utils';
 
 const router = express.Router();
 const TYPE_CONSTRAINTS = [...Object.keys(constants.resolvers), 'address', 'name'].join('|');
@@ -74,6 +81,9 @@ router.get(`/clear/:type(${TYPE_CONSTRAINTS})/:id`, async (req, res) => {
     }
     res.status(result ? 200 : 404).json({ status: result ? 'ok' : 'not found' });
   } catch (err) {
+    if (err instanceof InvalidQueryError) {
+      return res.status(400).json({ status: 'error', error: err.message || 'invalid id' });
+    }
     capture(err);
     res.status(500).json({ status: 'error', error: 'failed to clear cache' });
   }
@@ -89,7 +99,10 @@ router.get(`/:type(${TYPE_CONSTRAINTS})/:id`, async (req, res) => {
       type,
       req.query
     ));
-  } catch {
+  } catch (err) {
+    if (err instanceof InvalidQueryError) {
+      return res.status(400).json({ status: 'error', error: err.message || 'invalid id' });
+    }
     return res.status(500).json({ status: 'error', error: 'failed to load content' });
   }
 

src/getOwner/index.ts

@@ -1,6 +1,7 @@
-import { Address, Handle } from '../utils';
+import { ValidatedHandle } from '../helpers/validation';
+import { Address } from '../utils';
 import shibarium from './shibarium';
 
-export default async function getOwner(handle: Handle, chainId = '1'): Promise<Address> {
+export default async function getOwner(handle: ValidatedHandle, chainId = '1'): Promise<Address> {
   return shibarium(handle, chainId);
 }

src/helpers/validation.ts

@@ -6,33 +6,66 @@ import { z } from 'zod';
 export const MAX_LOOKUP_ADDRESSES = 50;
 export const MAX_RESOLVE_NAMES = 5;
 
+// Branded (nominal) types. zod's .brand() makes the parsed output structurally
+// distinct from a plain string so the compiler can enforce that only values
+// that went through one of these schemas reach the resolvers. There is no
+// runtime difference: an `Address` is still a string at runtime.
+//
 // Accepts both EVM addresses (0x + 40 hex chars) and Starknet addresses
 // (0x + 64 hex chars), matching isEvmAddress / isStarknetAddress.
-const addressString = z
+export const addressSchema = z
   .string()
   .regex(/^0x[a-fA-F0-9]{40}$/, 'must be a valid address')
-  .or(z.string().regex(/^0x[a-fA-F0-9]{64}$/, 'must be a valid address'));
+  .or(z.string().regex(/^0x[a-fA-F0-9]{64}$/, 'must be a valid address'))
+  .brand('Address');
+
+// Branded INPUT type: a string that has been validated as an address by zod.
+// Distinct from the plain `Address` value alias in utils.ts so the compiler can
+// enforce that the resolver entry points only receive validated input.
+export type ValidatedAddress = z.infer<typeof addressSchema>;
+
+// A domain handle (e.g. "vitalik.eth"): a non-empty string containing a dot.
+export const handleSchema = z
+  .string()
+  .regex(/^[^\s]*\.[^\s]*$/, 'must be a valid handle')
+  .brand('Handle');
+
+// Branded INPUT type: a string validated as a handle by zod.
+export type ValidatedHandle = z.infer<typeof handleSchema>;
 
 export const lookupAddressesSchema = z
-  .array(addressString)
+  .array(addressSchema)
   .min(1, 'params must contain at least one address')
   .max(MAX_LOOKUP_ADDRESSES, `params must contain less than ${MAX_LOOKUP_ADDRESSES} items`);
 
 // resolve_names receives domain handles (e.g. "vitalik.eth"), not addresses.
-const handleString = z.string().regex(/^[^\s]*\.[^\s]*$/, 'must be a valid handle');
-
 export const resolveNamesSchema = z
-  .array(handleString)
+  .array(handleSchema)
   .min(1, 'params must contain at least one name')
   .max(MAX_RESOLVE_NAMES, `params must contain less than ${MAX_RESOLVE_NAMES} items`);
 
-// lookup_domains receives a single EVM address string.
+// lookup_domains receives a single EVM address string. EVM-only, so it uses a
+// narrower regex than the generic address schema (which also accepts Starknet),
+// but outputs the same Address brand.
 export const lookupDomainsSchema = z
   .string()
-  .regex(/^0x[a-fA-F0-9]{40}$/, 'params must be a valid address');
+  .regex(/^0x[a-fA-F0-9]{40}$/, 'params must be a valid address')
+  .brand('Address');
 
 // get_owner receives a single domain handle string.
-export const getOwnerSchema = z.string().regex(/^[^\s]*\.[^\s]*$/, 'params must be a valid handle');
+export const getOwnerSchema = z
+  .string()
+  .regex(/^[^\s]*\.[^\s]*$/, 'params must be a valid handle')
+  .brand('Handle');
+
+// Avatar image route (GET /:type/:id). The `id`, once stripped of any chain
+// prefix (eip3770 "eth:0x..", caip10 "eip155:1:0x..", "did:..") and lowercased,
+// must be either a valid address or a valid handle/name. Address callers feed
+// the address resolvers (which require a branded Address), so this either-or is
+// what threads the brand into the avatar path.
+export const avatarIdSchema = z.union([addressSchema, handleSchema]);
+
+export type AvatarId = z.infer<typeof avatarIdSchema>;
 
 // Produces a short human readable summary of a ZodError, suitable for the
 // JSON-RPC error `data` field or an HTTP 400 message.

src/lookupDomains/index.ts

@@ -1,5 +1,5 @@
-import { isAddress } from '@ethersproject/address';
-import { Address, Handle } from '../utils';
+import { ValidatedAddress } from '../helpers/validation';
+import { Handle } from '../utils';
 import ens, { DEFAULT_CHAIN_ID as ENS_DEFAULT_CHAIN_ID } from './ens';
 import shibarium, { DEFAULT_CHAIN_ID as SHIBARIUM_DEFAULT_CHAIN_ID } from './shibarium';
 import unstoppableDomains, {
@@ -15,14 +15,16 @@ const DEFAULT_CHAIN_IDS = [
 ];
 
 export default async function lookupDomains(
-  address: Address,
+  address: ValidatedAddress,
   chains: string | string[] = DEFAULT_CHAIN_IDS
 ): Promise<Handle[]> {
   const promises: Promise<Handle[]>[] = [];
   let chainIds = Array.isArray(chains) ? chains : [chains];
   chainIds = [...new Set(chainIds.map(String))];
 
-  if (!isAddress(address)) return [];
+  // The address shape is now guaranteed by the branded Address type: the only
+  // caller (src/api.ts lookup_domains) validates it with lookupDomainsSchema at
+  // the boundary, so the previous runtime isAddress guard is redundant.
 
   RESOLVERS.forEach(resolver => {
     chainIds.forEach(chain => {

src/resolvers/basename.ts

@@ -2,8 +2,9 @@ import { getAvatar } from '../addressResolvers/basename';
 import { max } from '../constants.json';
 import { resize } from '../utils';
 import { fetchHttpImage } from './utils';
+import { AvatarId } from '../helpers/validation';
 
-export default async function resolve(nameOrAddress: string) {
+export default async function resolve(nameOrAddress: AvatarId) {
   try {
     const url = await getAvatar(nameOrAddress);
     if (!url) return false;

src/resolvers/ens.ts

@@ -1,18 +1,22 @@
-import { isAddress } from '@ethersproject/address';
 import { max } from '../constants.json';
 import { getProvider, resize } from '../utils';
 import { fetchHttpImage } from './utils';
 import { lookupAddresses } from '../addressResolvers';
-
-async function castToEnsName(nameOrAddress: string): Promise<string | undefined> {
-  if (isAddress(nameOrAddress)) {
-    return (await lookupAddresses([nameOrAddress]))[nameOrAddress];
+import { addressSchema, AvatarId } from '../helpers/validation';
+
+async function castToEnsName(nameOrAddress: AvatarId): Promise<string | undefined> {
+  // Re-derive the Address brand from the already validated id: when it is an
+  // address, feed the branded value into lookupAddresses; otherwise it is a
+  // handle and used as-is.
+  const asAddress = addressSchema.safeParse(nameOrAddress);
+  if (asAddress.success) {
+    return (await lookupAddresses([asAddress.data]))[asAddress.data];
   }
 
   return nameOrAddress;
 }
 
-export default async function resolve(nameOrAddress: string) {
+export default async function resolve(nameOrAddress: AvatarId) {
   try {
     const provider = getProvider(1);
     const ensName = await castToEnsName(nameOrAddress);

src/utils.ts

@@ -6,7 +6,17 @@ import { Response } from 'express';
 import sharp from 'sharp';
 import chains from './chains.json';
 import constants from './constants.json';
+import { AvatarId, avatarIdSchema, formatZodError } from './helpers/validation';
 
+// Thrown by parseQuery when the route `id` is neither a valid address nor a
+// valid handle. The route handler maps this to an HTTP 400.
+export class InvalidQueryError extends Error {}
+
+// Plain value-level aliases for addresses and handles as they flow THROUGH and
+// OUT of the resolvers (resolved values come back from the network as ordinary
+// strings). The branded, validated INPUT types live in helpers/validation.ts
+// (ValidatedAddress / ValidatedHandle / AvatarId) and are what the entry-point
+// functions accept, so only values that passed a zod schema can reach them.
 export type Address = string;
 export type Handle = string;
 export type ResolverType =
@@ -92,6 +102,17 @@ export async function parseQuery(id: string, type: ResolverType, query) {
   // console.log('Format', format);
 
   address = address.toLowerCase();
+
+  // Validate the resolver input at this REST boundary (the JSON-RPC boundary in
+  // src/api.ts is validated separately). The stripped id must be a valid
+  // address or handle; anything else is a 400, not a 500. The parsed value is
+  // branded (AvatarId) so the address path can thread it into the resolvers.
+  const parsedId = avatarIdSchema.safeParse(address);
+  if (!parsedId.success) {
+    throw new InvalidQueryError(formatZodError(parsedId.error));
+  }
+  const validatedAddress: AvatarId = parsedId.data;
+
   const size = 64;
   const maxSize = type.includes('-cover') ? constants.maxCover : constants.max;
   let s = query.s ? parseInt(query.s) : size;
@@ -102,7 +123,7 @@ export async function parseQuery(id: string, type: ResolverType, query) {
   if (h < 1 || h > maxSize || isNaN(h)) h = size;
 
   return {
-    address,
+    address: validatedAddress,
     network,
     networkId,
     w,