@ultimat3/admin 1.2.0 → 2.0.0

package/src/mcp.ts

@@ -27,12 +27,7 @@ import {
   type CrudResult,
 } from './crud';
 import type { AdminFieldType } from './fields';
-import {
-  type AdminMcpTool,
-  type AdminToolField,
-  adminMcpTools,
-  adminToolCatalog,
-} from './mcp-tools';
+import { type AdminMcpTool, adminMcpTools, adminToolCatalog } from './mcp-tools';
 import { confirmationToken } from './permissions';
 import type { AdminAction, AdminRow } from './registry';
 import { adminSearch } from './search';
@@ -187,13 +182,23 @@ const JSON_TYPE: Readonly<Record<AdminFieldType, NonNullable<JsonSchema['type']>
   file: 'string',
 };
 
-const inputSchema = (fields: readonly AdminToolField[]): JsonSchema => ({
+/**
+ * `additionalProperties` is closed for every derived CRUD tool — the admin knows every field an
+ * entity has, so an argument outside that set is a mistake worth refusing at the client.
+ *
+ * It is OPEN for an action tool, and that is the whole point: the fields `mcp-tools.ts` declares
+ * there are the admin's own envelope (`id`, `confirmation`), while the action's real input is its
+ * own Standard Schema, which this package does not own and does not project. Closed would refuse
+ * exactly the arguments the action needs; a made-up field list would describe a contract nobody
+ * validates against. Open lets the action's own validation be the one that decides.
+ */
+const inputSchema = (tool: AdminMcpTool): JsonSchema => ({
   type: 'object',
   properties: Object.fromEntries(
-    fields.map((field) => [field.name, { type: JSON_TYPE[field.type] }]),
+    tool.input.map((field) => [field.name, { type: JSON_TYPE[field.type] }]),
   ),
-  required: fields.filter((field) => field.required).map((field) => field.name),
-  additionalProperties: false,
+  required: tool.input.filter((field) => field.required).map((field) => field.name),
+  additionalProperties: tool.kind === 'action',
 });
 
 /**
@@ -256,7 +261,7 @@ function toMcpTool(opts: AdminMcpOptions, requestId: () => string, tool: AdminMc
   return {
     name: tool.name,
     description: tool.description,
-    inputSchema: inputSchema(tool.input),
+    inputSchema: inputSchema(tool),
     destructive: tool.destructive,
     // Visibility IS the gate: a tool this actor may not call is absent from `tools/list` and
     // answers ToolNotFound on call, never Forbidden — Forbidden would confirm the tool exists

package/src/nav.ts

@@ -2,6 +2,7 @@
 // `<entity>:read` pair that gates the page itself. A nav item an actor cannot open is not a
 // nav item — the alternative is a sidebar full of 403s.
 
+import { isAllowed } from './authz';
 import type { CrudCtx } from './crud';
 import { canOperate } from './crud';
 import type { AdminResource } from './resource';
@@ -12,6 +13,12 @@ export interface NavItem {
   readonly href: string;
   /** The entity this item lists, or `null` for a built-in page. */
   readonly entity: string | null;
+  /**
+   * What opening it needs. Set for a custom page (`pages.ts`), absent for a resource item —
+   * whose gate is its own `list` operation. Without it, an item with no entity was visible to
+   * everyone, which put a link to an ops screen in the sidebar of an actor the page refuses.
+   */
+  readonly permissions?: readonly string[];
 }
 
 export interface NavGroup {
@@ -86,6 +93,9 @@ export function visibleNav(
   ctx: CrudCtx,
 ): readonly NavGroup[] {
   const visible = (item: NavItem): boolean => {
+    if (item.permissions !== undefined && !isAllowed(ctx.authz, item.permissions, ctx.actor)) {
+      return false;
+    }
     if (item.entity === null) return true;
     const resource = resources.find((candidate) => candidate.name === item.entity);
     return resource !== undefined && canOperate(resource, 'list', ctx);

package/src/page-guard.tsx

@@ -0,0 +1,58 @@
+// The wrapper that makes a custom page's authz unskippable. `routes.ts` never hands the router
+// the author's component — it hands this one, which asks the SAME `decideAll` every CRUD call
+// and every nav item asks, audits the refusal, and only then calls the author's code.
+
+import { t } from '@ultimat3/i18n';
+import type { JSX } from 'solid-js';
+import type { AdminRoute } from './admin';
+import { deniedDraft } from './audit';
+import { type AdminDecision, decideAll } from './authz';
+import type { AdminPageComponent, AdminPageProps } from './pages';
+
+/**
+ * The refusal, rendered as the page. Not a redirect and not a 404: an operator who is missing a
+ * grant needs to read WHICH permission refused them, which is the same string the audit row and
+ * the `/_x` policy panel carry.
+ */
+export function AdminPageDenied(props: {
+  readonly titleKey: string;
+  readonly decision: AdminDecision;
+}): JSX.Element {
+  return (
+    <section class="x-admin-denied" role="alert">
+      <h1>{t(props.titleKey)}</h1>
+      <p>
+        {t('admin.denied.body', {
+          permission: props.decision.permission,
+          reason: props.decision.reason,
+        })}
+      </p>
+    </section>
+  );
+}
+
+/**
+ * Wrap once, at route-table build time. The author's component is never reachable from
+ * `adminRoutes()`, so "the page that forgot its policy line" has nowhere left to exist.
+ */
+export function guardedPage(route: AdminRoute, component: AdminPageComponent): AdminPageComponent {
+  return async (props: AdminPageProps): Promise<JSX.Element> => {
+    const decision = decideAll(props.ctx.authz, route.permissions, props.ctx.actor);
+    if (!decision.allowed) {
+      // The page IS the subject here, so its path is what the audit row names — there is no
+      // entity and no row id to key a refused screen by.
+      await props.ctx.audit.append(
+        deniedDraft({
+          requestId: props.ctx.requestId,
+          actor: props.ctx.actor,
+          operation: 'page',
+          kind: 'operation',
+          entity: route.path,
+          decision,
+        }),
+      );
+      return <AdminPageDenied titleKey={route.titleKey} decision={decision} />;
+    }
+    return component(props);
+  };
+}

package/src/pages.ts

@@ -0,0 +1,117 @@
+// The `pages:` seam — a screen no generator would write (a reconciliation fixer, a proxy health
+// board, a deploy button), declared as data so it lands in the SAME route table, nav and
+// permission pair the generated screens use. Nothing renders here: this file decides a page's
+// path and its permissions, so `routes.ts` has exactly one thing to guard.
+
+import type { JSX } from 'solid-js';
+import type { AdminRoute } from './admin';
+import type { CrudCtx } from './crud';
+import { AdminPagePathInvalidError, AdminPageUnguardedError } from './errors';
+import type { NavItem } from './nav';
+import { ADMIN_READ } from './permissions';
+
+/**
+ * What a page component is handed. `ctx` is the same per-request handle every CRUD call takes,
+ * and it is REQUIRED BY THE TYPE: a component that cannot be called without a ctx cannot be
+ * mounted without the guard that reads one.
+ */
+export interface AdminPageProps {
+  readonly ctx: CrudCtx;
+  readonly params: Readonly<Record<string, string>>;
+  readonly url: string;
+}
+
+/** An ordinary SolidJS component. Async, because a page with data has no `load` seam. */
+export type AdminPageComponent = (props: AdminPageProps) => JSX.Element | Promise<JSX.Element>;
+
+export interface AdminCustomPage {
+  /** Rooted at the admin's `basePath`: `/ops`, never `/admin/ops` and never `ops`. */
+  readonly path: string;
+  readonly titleKey: string;
+  readonly component: AdminPageComponent;
+  /** The nav group key. Omitted means reachable by URL but not linked. */
+  readonly navGroup?: string;
+  /** At least one. `admin:read` is composed in front of it; empty is X_ADMIN_PAGE_UNGUARDED. */
+  readonly permissions: readonly string[];
+}
+
+/**
+ * The frame's gate, then the page's own — the exact pair `permissionsForOperation()` builds for a
+ * resource, so a custom page is decided by the same `decideAll` and cannot invent a third shape.
+ */
+export function pagePermissions(page: AdminCustomPage): readonly string[] {
+  const out: string[] = [ADMIN_READ];
+  for (const permission of page.permissions) {
+    const trimmed = permission.trim();
+    if (trimmed !== '' && !out.includes(trimmed)) out.push(trimmed);
+  }
+  return out;
+}
+
+function assertGuarded(page: AdminCustomPage): void {
+  const declared = page.permissions.filter((permission) => permission.trim() !== '');
+  if (declared.length === 0) throw new AdminPageUnguardedError({ path: page.path });
+}
+
+function assertPath(page: AdminCustomPage, fullPath: string, taken: ReadonlySet<string>): void {
+  const refuse = (cause: string, fix: string): never => {
+    throw new AdminPagePathInvalidError({ path: page.path, cause, fix });
+  };
+  if (!page.path.startsWith('/')) {
+    refuse('is not rooted', `write path: '/${page.path}' — every page path starts with a slash`);
+  }
+  if (page.path.length < 2 || page.path.endsWith('/') || page.path.includes('//')) {
+    refuse('is not a usable path', "write path: '/ops' — one leading slash, no trailing slash");
+  }
+  if (taken.has(fullPath)) {
+    refuse(
+      `is already served by another admin route (${fullPath})`,
+      `rename the page, e.g. path: '${page.path}-ops'`,
+    );
+  }
+}
+
+/**
+ * Pages as routes. `taken` is every path the generated screens already claimed, so a page that
+ * would shadow `/admin/posts` fails at declaration rather than silently winning or losing a
+ * router race.
+ */
+export function pageRoutes(
+  basePath: string,
+  pages: readonly AdminCustomPage[],
+  taken: readonly string[],
+): readonly AdminRoute[] {
+  const claimed = new Set(taken);
+  const routes: AdminRoute[] = [];
+  for (const page of pages) {
+    assertGuarded(page);
+    const fullPath = `${basePath}${page.path}`;
+    assertPath(page, fullPath, claimed);
+    claimed.add(fullPath);
+    routes.push({
+      path: fullPath,
+      view: 'page',
+      entity: null,
+      titleKey: page.titleKey,
+      permissions: pagePermissions(page),
+      component: page.component,
+    });
+  }
+  return routes;
+}
+
+/** Nav entries for the pages that asked for one, carrying the permissions that hide them. */
+export function pageNavItems(
+  pages: readonly AdminCustomPage[],
+): readonly (NavItem & { readonly group: string })[] {
+  return pages
+    .filter((page) => page.navGroup !== undefined)
+    .map((page) => ({
+      key: page.path,
+      labelKey: page.titleKey,
+      href: page.path,
+      entity: null,
+      permissions: pagePermissions(page),
+      group: page.navGroup ?? '',
+    }));
+}

package/src/pagination.ts

@@ -71,6 +71,7 @@ export interface AdminPage<Row extends AdminRow> {
   readonly pageSize: number;
   readonly nextCursor: string | null;
   readonly prevCursor: string | null;
+  /** A page exists AFTER this one — what the Next control is enabled by, in both directions. */
   readonly hasMore: boolean;
 }
 
@@ -103,7 +104,21 @@ const cursorValue = (row: AdminRow, field: string): string => {
   return value === null || value === undefined ? '' : String(value);
 };
 
-/** Turn `limit + 1` rows into a page plus the cursors that walk off either end. */
+/**
+ * Turn `limit + 1` rows into a page plus the cursors that walk off either end.
+ *
+ * The extra row is on the side the keyset walked TOWARD, so the direction decides everything:
+ *  - `after` (and the first page, which has no cursor): the overflow row is the tail, and it means
+ *    a next page exists. A previous page exists iff a cursor got us here.
+ *  - `before`: the overflow row is the HEAD — the repo returns the page in the query's sort order,
+ *    so the row furthest back is index 0 — and it means a *previous* page exists. A next page
+ *    always exists, because paging backwards is only reachable from a later page.
+ *
+ * Reading `hasMore` as "the fetch overflowed" regardless of direction disabled Next on every
+ * backward page (the operator could not walk back to where they came from) and left Previous
+ * enabled past the first row; trimming the tail on a backward page silently skipped the row next
+ * to the cursor. One flag, both bugs.
+ */
 export function pageFrom<Row extends AdminRow>(
   resource: AdminResource<Row>,
   req: PageRequest,
@@ -111,11 +126,20 @@ export function pageFrom<Row extends AdminRow>(
 ): AdminPage<Row> {
   const sort = req.sort ?? resource.defaultSort;
   const pageSize = Math.max(1, Math.min(req.limit ?? resource.pageSize, 200));
-  const hasMore = fetched.length > pageSize;
-  const rows = hasMore ? fetched.slice(0, pageSize) : fetched;
+  const incoming = decodeAdminCursor(resource, req.cursor);
+  const backwards = incoming?.direction === 'before';
+  const overflow = fetched.length > pageSize;
+
+  const rows = !overflow
+    ? fetched
+    : backwards
+      ? fetched.slice(fetched.length - pageSize)
+      : fetched.slice(0, pageSize);
   const last = rows[rows.length - 1];
   const first = rows[0];
-  const incoming = decodeAdminCursor(resource, req.cursor);
+
+  const hasMore = backwards ? true : overflow;
+  const hasPrevious = backwards ? overflow : incoming !== null;
 
   return {
     rows,
@@ -132,7 +156,7 @@ export function pageFrom<Row extends AdminRow>(
           })
         : null,
     prevCursor:
-      incoming !== null && first !== undefined
+      hasPrevious && first !== undefined
         ? encodeAdminCursor(resource, {
             direction: 'before',
             field: sort.field,

package/src/registry.ts

@@ -120,6 +120,12 @@ export interface AdminListQuery {
    * row's id as the tie-break so pages stay stable when the sort column has duplicates.
    */
   readonly after?: KeysetBound;
+  /**
+   * The mirror of `after`. Rows come back in `sort`'s own order either way — the admin renders
+   * what the repo returns and never re-sorts — so on a `before` query the `limit + 1`st row is the
+   * one FURTHEST back, at index 0, and `pageFrom` trims the head rather than the tail. A repo that
+   * answered nearest-first would hand the operator a reversed page.
+   */
   readonly before?: KeysetBound;
 }
 

package/src/routes.ts

@@ -1,29 +1,58 @@
-// The one bridge from the admin's route table to @ultimat3/render. Every admin page is
-// `spa`: it is behind auth, so there is nothing to prerender and nothing a CDN may hold —
-// and `network-only` keeps a stale org's rows out of a service worker cache.
+// The one bridge from the admin's route table to @ultimat3/render, and the one place a policy
+// is composed onto an admin page. A generated view is `spa`: it is behind auth, so there is
+// nothing to prerender and nothing a CDN may hold — and `network-only` keeps a stale org's rows
+// out of a service worker cache. A custom page is `ssr`, because its guard runs on the server.
 
 import { t } from '@ultimat3/i18n';
-import { defineRoute } from '@ultimat3/render';
+import { defineRoute, type RouteGuard } from '@ultimat3/render';
 import type { AdminApp, AdminRoute } from './admin';
+import { AdminPagePathInvalidError, AdminPageUnguardedError } from './errors';
+import { guardedPage } from './page-guard';
+import type { AdminPageComponent } from './pages';
 
 export interface AdminRouteConfig {
   readonly path: string;
   readonly view: AdminRoute['view'];
   readonly entity: string | null;
   readonly permissions: readonly string[];
+  /** The GUARDED component of a custom page; `null` for a generated view. */
+  readonly component: AdminPageComponent | null;
+  /**
+   * The coarse gate, already composed — the SAME object `config.policy` carries. It is here, and
+   * not read back off `config`, because `RouteConfig.policy` is optional: a host that serves an
+   * admin URL from its own file has to be able to take the gate without proving it exists.
+   */
+  readonly policy: RouteGuard;
   readonly config: ReturnType<typeof defineRoute>;
 }
 
+/**
+ * The author never writes this `defineRoute` call, so the author cannot omit its `policy` —
+ * which is the whole mechanism. The coarse gate is `permissions[0]` (always `admin:read`, put
+ * there by `permissionsForOperation`/`pagePermissions`); the rest of the pair is decided per
+ * request by `decideAll`, in `crud.ts` for a generated view and in `page-guard.tsx` for a page.
+ * An empty list is refused here too: `render: 'spa'` and `'ssr'` would both ship a public shell.
+ */
 export function adminRouteConfig(route: AdminRoute): AdminRouteConfig {
+  const permission = route.permissions[0];
+  if (permission === undefined) throw new AdminPageUnguardedError({ path: route.path });
+  const custom = route.component !== undefined;
+  const policy: RouteGuard = { permission };
+
   return {
     path: route.path,
     view: route.view,
     entity: route.entity,
     permissions: route.permissions,
+    component: route.component === undefined ? null : guardedPage(route, route.component),
+    policy,
     config: defineRoute({
-      render: 'spa',
+      // A custom page renders server data behind the guard; a generated view is a shell that
+      // fetches through the admin's own gated calls. One mode each, never an author's choice.
+      render: custom ? 'ssr' : 'spa',
       offline: 'network-only',
-      hydrate: 'idle',
+      hydrate: custom ? 'never' : 'idle',
+      policy,
       meta: () => ({ title: t(route.titleKey) }),
     }),
   };
@@ -33,3 +62,32 @@ export function adminRouteConfig(route: AdminRoute): AdminRouteConfig {
 export function adminRoutes(app: AdminApp): readonly AdminRouteConfig[] {
   return app.routes.map(adminRouteConfig);
 }
+
+/**
+ * The one route the admin declares for `path` — the lookup a host performs when it serves an admin
+ * URL from its own file rather than from `adminRoutes()`.
+ *
+ * It exists because the alternative is what the deployed demo shipped: a page file typing
+ * `policy: { permission: 'admin:read' }` beside a route table that separately declared
+ * `permissionsForOperation(...)` for the same URL. Two declarations of one URL's authz agree until
+ * one of them is edited, and nothing was ever going to notice. Reading the gate from here means
+ * there is one declaration and one reader.
+ *
+ * A path the table does not declare is refused rather than answered with a default: a mount with
+ * no route is a screen whose permissions nothing composed, which is exactly the shape `pages:`
+ * exists to make impossible.
+ */
+export function adminRouteFor(app: AdminApp, path: string): AdminRouteConfig {
+  const route = app.routes.find((candidate) => candidate.path === path);
+  if (route === undefined) {
+    throw new AdminPagePathInvalidError({
+      path,
+      cause: 'is not a route this admin declares',
+      fix:
+        'serve one of the paths defineAdmin() built — ' +
+        `${app.routes.map((candidate) => candidate.path).join(', ')} — ` +
+        'or declare this one in `pages:` on defineAdmin()',
+    });
+  }
+  return adminRouteConfig(route);
+}

package/src/search.ts

@@ -2,6 +2,7 @@
 // search config to drift from the entities, and no result an actor could not have opened —
 // the same `admin:read` + `<entity>:read` pair gates the hit and the detail page it links to.
 
+import { expectedQueryLoop } from '@ultimat3/db';
 import type { CrudCtx } from './crud';
 import { canOperate } from './crud';
 import type { AdminFilter, AdminRow } from './registry';
@@ -41,6 +42,11 @@ export interface AdminSearchInput {
  * One query per searchable field rather than one query with an OR: the admin's query IR is
  * a conjunction by design (each filter maps to an indexed predicate), and three small
  * indexed lookups beat one unindexed disjunction.
+ *
+ * That argument is declared to the runtime and not only to the reader — `expectedQueryLoop`
+ * carries it onto every statement the loop issues, so a statement diagnostic reports the loops
+ * nobody argued for and never this one. At most `MAX_FIELDS_PER_RESOURCE` queries, and the scope
+ * ends with the loop: anything the repo does afterwards is judged normally.
  */
 async function searchResource(
   resource: AdminResource,
@@ -52,24 +58,29 @@ async function searchResource(
   const seen = new Set<string>();
   const hits: AdminSearchHit[] = [];
 
-  for (const field of fields) {
-    const where: readonly AdminFilter[] = [{ field: field.name, op: 'contains', value: term }];
-    const rows = await repo.list({ where, sort: resource.defaultSort, limit });
-    for (const row of rows) {
-      const id = rowId(row, resource.idField);
-      if (id === '' || seen.has(id)) continue;
-      seen.add(id);
-      hits.push({
-        entity: resource.name,
-        id,
-        label: labelOf(row, resource),
-        matchedField: field.name,
-        href: `${resource.path}/${id}`,
-      });
-      if (hits.length >= limit) return hits;
-    }
-  }
-  return hits;
+  return expectedQueryLoop(
+    'admin search runs one indexed lookup per text field, which beats one unindexed OR',
+    async () => {
+      for (const field of fields) {
+        const where: readonly AdminFilter[] = [{ field: field.name, op: 'contains', value: term }];
+        const rows = await repo.list({ where, sort: resource.defaultSort, limit });
+        for (const row of rows) {
+          const id = rowId(row, resource.idField);
+          if (id === '' || seen.has(id)) continue;
+          seen.add(id);
+          hits.push({
+            entity: resource.name,
+            id,
+            label: labelOf(row, resource),
+            matchedField: field.name,
+            href: `${resource.path}/${id}`,
+          });
+          if (hits.length >= limit) return hits;
+        }
+      }
+      return hits;
+    },
+  );
 }
 
 function labelOf(row: AdminRow, resource: AdminResource): string {

package/src/widget-value.ts

@@ -4,6 +4,7 @@
 // this returns and make no decisions of their own.
 
 import type { Money } from '@ultimat3/money';
+import { isCurrencyCode } from '@ultimat3/schema';
 import { AdminFieldUnsupportedError } from './errors';
 import type { AdminField } from './fields';
 
@@ -12,6 +13,18 @@ export interface WidgetContext {
   readonly timeZone: string;
   /** BCP-47, for the number/date/money formatters the widgets call. */
   readonly locale: string;
+  /**
+   * Where a foreign-key value links to, or `null` for "do not link it". Absent renders the id as
+   * plain text.
+   *
+   * WHY a seam and not a derivation: the widget used to build `/${entity}s/${value}`, which is
+   * English pluralisation by string concatenation and drops the admin's own `basePath` — a link
+   * that is wrong on every admin not mounted at `/` and on every entity whose plural is not a
+   * trailing `s`. The route table is `AdminApp`'s (`basePath` + `AdminResource.path`, which is
+   * already pluralised once, in `resource.ts`), and a widget three layers down cannot see it. The
+   * caller that builds this context can. A wrong link is worse than no link.
+   */
+  readonly hrefFor?: (entity: string, id: string) => string | null;
 }
 
 export interface SelectOption {
@@ -59,8 +72,6 @@ const fail = (field: AdminField, cause: string, fix: string): never => {
   throw new AdminFieldUnsupportedError({ entity: field.entity, field: field.name, cause, fix });
 };
 
-const CURRENCY = /^[A-Z]{3}$/;
-
 /**
  * `money()` puts a `bigint` on the row — Postgres `bigint` minor units — where `Money` is a
  * number. This is the one place that widening happens, and it refuses rather than round: a
@@ -101,7 +112,12 @@ export function assertMoney(field: AdminField, value: unknown): Money | null {
     );
   }
   const currency = typeof bag.currency === 'string' ? bag.currency : field.currency;
-  if (currency === undefined || !CURRENCY.test(currency)) {
+  // `isCurrencyCode` is `@ultimat3/schema`'s (tier 0), never a local regex: this widget refuses
+  // exactly what `t.money`, the published OpenAPI `pattern` and the Postgres CHECK refuse, so a
+  // row the app wrote can never be one the admin declines to render. It takes `unknown`, which is
+  // what makes the `undefined` case — no row currency and no declared `field.currency` — the same
+  // branch as a malformed one.
+  if (!isCurrencyCode(currency)) {
     return fail(
       field,
       `money has no ISO-4217 currency (got ${String(bag.currency)})`,

package/src/widgets.tsx

@@ -2,6 +2,7 @@
 // switch, so money is a Money widget and a timestamp is a DateTime widget with a zone in
 // every one of those places — there is no second place to get it wrong.
 
+import { safeUrl } from '@ultimat3/core';
 import { t } from '@ultimat3/i18n';
 import {
   Checkbox,
@@ -65,7 +66,7 @@ const inputValueFor = (iso: string, precision: 'date' | 'instant'): string =>
   iso.slice(0, precision === 'date' ? 10 : 16);
 
 /** Read-mode rendering of already-guarded props. Never formats; the widgets do that. */
-function readView(props: WidgetProps, field: AdminField): JSX.Element {
+function readView(props: WidgetProps, field: AdminField, ctx: WidgetContext): JSX.Element {
   switch (props.widget) {
     case 'money':
       return props.value === null ? (
@@ -95,17 +96,18 @@ function readView(props: WidgetProps, field: AdminField): JSX.Element {
       );
     case 'json-editor':
       return <pre class="x-admin-json">{props.value}</pre>;
-    case 'reference':
-      return props.value === null ? (
-        <span>{t('admin.value.empty')}</span>
-      ) : (
-        <a href={`/${props.entity}s/${props.value}`}>{props.value}</a>
-      );
+    case 'reference': {
+      if (props.value === null) return <span>{t('admin.value.empty')}</span>;
+      // `ctx.hrefFor` or nothing. The route table lives on `AdminApp`; this file only ever knew
+      // the target entity's NAME, and turning that into a URL by appending an `s` is a guess.
+      const href = ctx.hrefFor?.(props.entity, props.value) ?? null;
+      return href === null ? <span>{props.value}</span> : <a href={href}>{props.value}</a>;
+    }
     case 'upload':
       return props.value === null ? (
         <span>{t('admin.value.empty')}</span>
       ) : (
-        <a href={props.value.url}>{props.value.name}</a>
+        <a href={safeUrl(props.value.url, 'href') ?? undefined}>{props.value.name}</a>
       );
     default:
       return <span>{String(props.value ?? '')}</span>;
@@ -258,5 +260,5 @@ function locales(): readonly string[] {
 
 export function Widget(input: WidgetInput): JSX.Element {
   const props = widgetProps(input.field, input.value, input.ctx);
-  return input.mode === 'read' ? readView(props, input.field) : editView(props, input);
+  return input.mode === 'read' ? readView(props, input.field, input.ctx) : editView(props, input);
 }