Programmatic pages

Why it matters

An ungated dynamic route generates a page for any slug anyone types, including slugs an attacker generates. That is how a site accidentally publishes ten thousand thin pages.

How to verify

curl -s -o /dev/null -w '%{http_code}\n' https://example.com/glossary/not-a-real-term

Then confirm 404, not 200.

Implementation

/**
 * Code Kit: entity gating.
 * Implements checks: pseo-entity-gate, found-404-returns-404
 *
 * An ungated dynamic route renders a page for any slug it is given, including
 * slugs a crawler invented by mangling a URL. Each one is an indexable page
 * with no content. This module is the gate.
 */

export type GatedEntity = { slug: string };

export type EntityGate<T extends GatedEntity> = {
  /** Every valid slug, for static generation. */
  slugs: () => string[];
  /** Returns undefined for anything not on the list. Never a partial match. */
  resolve: (slug: string) => T | undefined;
  /** Canonical slug to redirect to, or undefined. Aliases never render. */
  resolveAlias: (slug: string) => string | undefined;
  all: () => readonly T[];
  size: number;
};

export function createEntityGate<T extends GatedEntity>(
  entities: readonly T[],
  aliases: Readonly<Record<string, string>> = {},
): EntityGate<T> {
  const bySlug = new Map(entities.map((entity) => [entity.slug, entity]));

  // A duplicate slug means two entities compete for one URL. Fail loudly at
  // module load rather than serving whichever one won the Map insertion.
  if (bySlug.size !== entities.length) {
    const seen = new Set<string>();
    const duplicates = entities
      .map((entity) => entity.slug)
      .filter((slug) => (seen.has(slug) ? true : (seen.add(slug), false)));
    throw new Error(`Duplicate entity slugs: ${[...new Set(duplicates)].join(", ")}`);
  }

  return {
    slugs: () => entities.map((entity) => entity.slug),
    resolve: (slug) => bySlug.get(slug),
    resolveAlias: (slug) => {
      const target = aliases[slug];
      return target && bySlug.has(target) ? target : undefined;
    },
    all: () => entities,
    size: entities.length,
  };
}

/**
 * Slug normalisation for the URLs you generate, not for the ones you receive.
 * Receiving a slug that needs normalising means the link that produced it is
 * wrong; fix the link rather than accepting both forms.
 */
export function toSlug(value: string): string {
  return value
    .toLowerCase()
    .normalize("NFKD")
    .replace(/[̀-ͯ]/g, "")
    .replace(/[^a-z0-9]+/g, "-")
    .replace(/^-+|-+$/g, "");
}

Why it matters

Remove the entity name from the page. If nothing unique remains, the tier is doorway pages and shipping it risks the whole domain, not just the tier.

How to verify

Take three pages from the tier, delete every occurrence of the entity name, and diff them. If the diff is empty, do not publish.

Why it matters

Numbers are the cheapest form of genuine uniqueness and the hardest to fake at scale. A page with six entity-specific figures cannot be a template with the name swapped.

How to verify

Pick five random pages in the tier and confirm at least four numeric values differ across all five.

Why it matters

A per-entity FAQ answer that contains a real figure is quotable by an answer engine. The same sentence with only the name changed is recognisably generated.

How to verify

Compare the FAQ answers on two pages in the tier. If they differ only in the entity name, they are not computed.

Why it matters

A template that prints 0 or an em dash when data is missing is asserting something false. Labelling the gap is both accurate and, unexpectedly, a trust signal.

How to verify

Find an entity with incomplete source data and confirm the page says so in words rather than rendering a zero.

Why it matters

A flat tier of 1,689 pages linked only from a paginated index gets crawled once. Sibling links turn it into a connected graph a crawler can traverse.

How to verify

On any tier page, count internal links to the same tier and confirm at least six, plus one to the hub.

Why it matters

Querying a database at build time makes the build non-reproducible and couples deploys to database availability. Committed snapshots make a data change a reviewable diff.

How to verify

Confirm the generated module exports a `*_UPDATED_AT` constant and that the file is in version control.

Why it matters

A tier rendered on request depends on the database being up for the sales funnel to work, and pays a cold-start cost on the first crawl of every page.

How to verify

Check the build output and confirm the tier routes are listed as static, then confirm a request to a tier page returns a cache hit.