@ultimat3/admin 22.15.0 → 24.0.0

package/src/screen-frame.tsx

@@ -0,0 +1,167 @@
+// What every mounted screen shares: the shape of its request and its answer, the shell it is
+// framed in, and the refusal it renders. A screen DECIDES first — through `crud.ts`,
+// `action-gate.ts` or `page-guard.tsx` — and only then builds a body, so the frame is the one
+// place a status meets a document.
+
+import { localeConfig, t } from '@ultimat3/i18n';
+import { ErrorState } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import type { AdminApp, AdminRoute } from './admin';
+import { type AdminDecision, decideAll } from './authz';
+import { type CrudCtx, canOperate } from './crud';
+import { AdminFilterInvalidError } from './errors';
+import { AdminLayout } from './layout';
+import { AdminPageDenied, auditRefusal } from './page-guard';
+import type { AdminPageProps } from './pages';
+import type { RelationData } from './relations';
+import type { AdminResource } from './resource';
+import { LOOKUP_SEGMENT } from './resource-list';
+import type { WidgetContext } from './widget-value';
+
+/** One request to one admin route: a GET, or the form a screen posted back at itself. */
+export interface AdminRouteRequest extends AdminPageProps {
+  readonly method: 'GET' | 'POST';
+  /** The parsed form. `null` on a GET; a POST with no fields is `{}`. */
+  readonly form: Readonly<Record<string, unknown>> | null;
+}
+
+export type AdminRouteResponse =
+  | {
+      readonly kind: 'document';
+      readonly status: number;
+      /** The framed screen: shell, nav for this actor, and the body. */
+      readonly body: JSX.Element;
+    }
+  /** A write that worked: the browser is sent to the row or the list it changed. Always a 303. */
+  | { readonly kind: 'redirect'; readonly location: string };
+
+/** A mounted screen. `routes.ts` is the only thing that hands one to a host. */
+export type AdminScreen = (request: AdminRouteRequest) => Promise<AdminRouteResponse>;
+
+/**
+ * The zone and locale every formatter on a screen reads — the ACTOR's, never the server's — and
+ * what the page read of the resources it references. `relations` is the whole of it: a widget
+ * shows a label or an option list the page already holds, and never reads a row of its own.
+ */
+export function widgetContextOf(
+  app: AdminApp,
+  ctx: CrudCtx,
+  relations: ReadonlyMap<string, RelationData> = new Map(),
+): WidgetContext {
+  const target = (entity: string): AdminResource | undefined =>
+    app.resources.find((resource) => resource.name === entity);
+  return {
+    timeZone: ctx.actor.timeZone ?? 'UTC',
+    // The app's declared default, read back off the framework — never a second literal.
+    locale: ctx.actor.locale ?? localeConfig().fallback,
+    // The route table is the app's; a widget three layers down gets a link or no link.
+    hrefFor: (entity, id) => {
+      const found = target(entity);
+      return found === undefined ? null : `${app.basePath}${found.path}/${id}`;
+    },
+    labelFor: (entity, id) => relations.get(entity)?.labels.get(id),
+    optionsFor: (entity) => relations.get(entity)?.options ?? null,
+    lookupHref: (entity) => {
+      const found = target(entity);
+      // Only a resource whose list this actor may read has a lookup to send them to.
+      return found === undefined || !canOperate(found, 'list', ctx)
+        ? null
+        : lookupHref(app.basePath, found);
+    },
+  };
+}
+
+/** Where a resource's lookup screen lives. One spelling, read by the route table and every link. */
+export const lookupHref = (basePath: string, resource: Pick<AdminResource, 'path'>): string =>
+  `${basePath}${resource.path}/${LOOKUP_SEGMENT}`;
+
+export function framed(
+  app: AdminApp,
+  request: AdminRouteRequest,
+  /** The screen's `<h1>`. `null` when the body carries its own — a refusal does. */
+  titleKey: string | null,
+  body: JSX.Element,
+  status = 200,
+): AdminRouteResponse {
+  return {
+    kind: 'document',
+    status,
+    body: (
+      <AdminLayout
+        app={app}
+        nav={app.navFor(request.ctx)}
+        currentPath={new URL(request.url).pathname}
+        actor={request.ctx.actor}
+        {...(titleKey === null ? {} : { title: t(titleKey) })}
+      >
+        {body}
+      </AdminLayout>
+    ),
+  };
+}
+
+/** A refusal the gate already audited: the page names the permission, and the status is 403. */
+export function refused(
+  app: AdminApp,
+  request: AdminRouteRequest,
+  titleKey: string,
+  decision: AdminDecision,
+): AdminRouteResponse {
+  return framed(
+    app,
+    request,
+    null,
+    <AdminPageDenied titleKey={titleKey} decision={decision} />,
+    403,
+  );
+}
+
+/**
+ * A refusal decided HERE rather than inside a crud call — a form's GET, a page — so the audit
+ * entry is written here too. The page is the subject: its path is what the row names.
+ */
+export async function refusedPage(
+  app: AdminApp,
+  request: AdminRouteRequest,
+  route: AdminRoute,
+  decision: AdminDecision,
+): Promise<AdminRouteResponse> {
+  await auditRefusal(request.ctx, route.path, decision);
+  return refused(app, request, route.titleKey, decision);
+}
+
+/** A URL the admin serves and a thing it does not have: a row that is gone, an unknown action. */
+export function missing(
+  app: AdminApp,
+  request: AdminRouteRequest,
+  titleKey: string,
+  body: JSX.Element,
+): AdminRouteResponse {
+  return framed(app, request, titleKey, body, 404);
+}
+
+/**
+ * The wrapper that makes a screen's authz unskippable: a custom page, the dashboard, jobs, audit
+ * and search are all built through it, so "the screen that forgot its policy line" has nowhere to
+ * exist. It asks the SAME `decideAll` every CRUD call and every nav item asks, audits the
+ * refusal, answers it 403, and only then calls the body. A resource screen is the one thing not
+ * built here — `crud.ts` decides those, because only it holds the row a row-level rule reads.
+ */
+export function guardedScreen(
+  app: AdminApp,
+  route: AdminRoute,
+  body: (request: AdminRouteRequest) => JSX.Element | Promise<JSX.Element>,
+): AdminScreen {
+  return async (request) => {
+    const decision = decideAll(request.ctx.authz, route.permissions, request.ctx.actor);
+    if (!decision.allowed) return refusedPage(app, request, route, decision);
+    try {
+      return framed(app, request, route.titleKey, await body(request));
+    } catch (error) {
+      // A body that refuses its URL — a parameter it does not answer — is the list's 400: the
+      // error, naming what the screen does answer. Anything else is not this frame's to render.
+      if (!(error instanceof AdminFilterInvalidError)) throw error;
+      return framed(app, request, route.titleKey, <ErrorState error={error} />, 400);
+    }
+  };
+}

package/src/screen-home.tsx

@@ -0,0 +1,201 @@
+// `/admin` — the dashboard: every resource this actor may open, the decision behind each of its
+// operations, and the app-wide actions. No row is read here: a dashboard that listed five rows of
+// every resource would be one query per entity on every visit to the front page.
+
+import { t } from '@ultimat3/i18n';
+import { Card } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import { AdminActionForm } from './action-form';
+import { actionButtons, invokeAdminAction } from './action-gate';
+import { decodeActionInput, postedActionInput } from './action-input';
+import { ACTION_OPERATION, ACTION_PARAM, AdminActions, OPERATION_FIELD } from './actions';
+import type { AdminApp, AdminRoute } from './admin';
+import styles from './admin.module.scss';
+import { decideAll } from './authz';
+import type { CrudCtx } from './crud';
+import { canOperate, decideOperation, permissionsForOperation } from './crud';
+import { posted } from './form-decode';
+import { ADMIN_OPERATIONS, type AdminOperation, confirmationToken } from './permissions';
+import type { AdminAction } from './registry';
+import type { AdminResource } from './resource';
+import {
+  type AdminRouteRequest,
+  type AdminRouteResponse,
+  type AdminScreen,
+  framed,
+  refused,
+  refusedPage,
+} from './screen-frame';
+import type { ValidationIssue } from './validate';
+
+/** One row of an operation matrix: the decision the dashboard renders AND the call obeys. */
+export interface OperationDecision {
+  readonly operation: AdminOperation;
+  readonly allowed: boolean;
+  readonly permissions: readonly string[];
+  readonly reason: string;
+}
+
+/**
+ * Every operation the resource OFFERS, with its decision. This IS the view-only proof, rendered
+ * rather than asserted. One it does not offer has no row: "denied" would read as a missing grant
+ * the operator should ask for, when no grant opens it.
+ */
+export const operationMatrix = (
+  resource: AdminResource,
+  ctx: CrudCtx,
+): readonly OperationDecision[] =>
+  ADMIN_OPERATIONS.filter((operation) => resource.operations.includes(operation)).map(
+    (operation) => {
+      const decision = decideOperation(resource, operation, ctx);
+      return {
+        operation,
+        allowed: decision.allowed,
+        permissions: permissionsForOperation(resource.permission, operation),
+        reason: decision.reason,
+      };
+    },
+  );
+
+/**
+ * The permission matrix, rendered. A reader can see that `create`, `update` and `delete` are
+ * refused and WHICH permission refused them — the same decision the call obeys, not a note about
+ * a button that was left out.
+ */
+export function OperationMatrix(props: {
+  readonly rows: readonly OperationDecision[];
+}): JSX.Element {
+  return (
+    <table class={styles['matrix']}>
+      <thead>
+        <tr>
+          <th>{t('admin.matrix.operation')}</th>
+          <th>{t('admin.matrix.permissions')}</th>
+          <th>{t('admin.matrix.verdict')}</th>
+        </tr>
+      </thead>
+      <tbody>
+        {props.rows.map((row) => (
+          <tr class={row.allowed ? styles['allowed'] : styles['denied']}>
+            <td>{t(`admin.operation.${row.operation}`)}</td>
+            <td class={styles['mono']}>{row.permissions.join(' + ')}</td>
+            <td>
+              {row.allowed
+                ? t('admin.matrix.allowed')
+                : `${t('admin.matrix.deniedBy')} ${row.reason}`}
+            </td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+/** An app-wide action's POST: the same gate, with no row for a subject. */
+async function globalWrite(
+  app: AdminApp,
+  route: AdminRoute,
+  request: AdminRouteRequest,
+  form: Readonly<Record<string, unknown>>,
+): Promise<AdminRouteResponse> {
+  const name = posted(form, 'name') ?? '';
+  const action =
+    posted(form, OPERATION_FIELD) === ACTION_OPERATION
+      ? app.globalActions.find((declared) => declared.name === name)
+      : undefined;
+  if (action === undefined) {
+    return framed(app, request, route.titleKey, <p>{t('admin.actions.unknown')}</p>, 404);
+  }
+  const confirmation = posted(form, 'confirmation');
+  const result = await invokeAdminAction({
+    action,
+    input: decodeActionInput(action, form),
+    actor: request.ctx.actor,
+    authz: request.ctx.authz,
+    audit: request.ctx.audit,
+    requestId: request.ctx.requestId,
+    ...(confirmation === undefined ? {} : { confirmation }),
+  });
+  if (result.ok) return { kind: 'redirect', location: app.basePath };
+  if (result.kind === 'invalid') {
+    return globalForm(app, route, request, action, postedActionInput(action, form), result.issues);
+  }
+  // A global action has no row, so its `when` is never asked: only a refusal is left.
+  return refused(app, request, route.titleKey, result.decision);
+}
+
+/** An app-wide action's own form: `GET /admin?action=<name>`, and its refused post. */
+function globalForm(
+  app: AdminApp,
+  route: AdminRoute,
+  request: AdminRouteRequest,
+  action: AdminAction,
+  values: Readonly<Record<string, string>>,
+  issues: readonly ValidationIssue[],
+): AdminRouteResponse {
+  return framed(
+    app,
+    request,
+    route.titleKey,
+    <AdminActionForm
+      action={action}
+      href={app.basePath}
+      operation={ACTION_OPERATION}
+      values={values}
+      issues={issues}
+      confirmation={action.destructive === true ? confirmationToken('admin', '') : null}
+      subject={t('admin.actions.subject.app')}
+      cancelHref={app.basePath}
+    />,
+    issues.length === 0 ? 200 : 422,
+  );
+}
+
+export function homeScreen(app: AdminApp, route: AdminRoute): AdminScreen {
+  return async (request) => {
+    const decision = decideAll(request.ctx.authz, route.permissions, request.ctx.actor);
+    if (!decision.allowed) return refusedPage(app, request, route, decision);
+    if (request.method === 'POST') return globalWrite(app, route, request, request.form ?? {});
+    const asked = new URL(request.url).searchParams.get(ACTION_PARAM);
+    if (asked !== null) {
+      // Only an action this actor may run: a link to a form is never a way round a missing button.
+      const offered = actionButtons({
+        actions: app.globalActions,
+        actor: request.ctx.actor,
+        authz: request.ctx.authz,
+      }).some((button) => button.name === asked);
+      const action = app.globalActions.find((declared) => declared.name === asked);
+      if (!offered || action === undefined) {
+        return framed(app, request, route.titleKey, <p>{t('admin.actions.unknown')}</p>, 404);
+      }
+      return globalForm(app, route, request, action, {}, []);
+    }
+
+    const open = app.resources.filter((resource) => canOperate(resource, 'list', request.ctx));
+    return framed(
+      app,
+      request,
+      route.titleKey,
+      <div class={styles['panel']}>
+        <AdminActions
+          actions={app.globalActions}
+          actor={request.ctx.actor}
+          authz={request.ctx.authz}
+          href={app.basePath}
+        />
+        {open.length === 0 ? <p class={styles['note']}>{t('admin.actions.none')}</p> : null}
+        {open.map((resource) => (
+          <Card
+            header={
+              <h2>
+                <a href={`${app.basePath}${resource.path}`}>{t(resource.titleKey)}</a>
+              </h2>
+            }
+          >
+            <OperationMatrix rows={operationMatrix(resource, request.ctx)} />
+          </Card>
+        ))}
+      </div>,
+    );
+  };
+}

package/src/screen-lookup.tsx

@@ -0,0 +1,157 @@
+// A resource's lookup screen: the picker for every filter and every input that references it.
+// Zero script — a GET form over the label, results as links, keyset paging as links. Opened from
+// a filter it carries `return` and `as`, and each result links back to that list with the
+// parameter set to the row's id; opened on its own, a result opens the row.
+
+import { t } from '@ultimat3/i18n';
+import { Button, Card, ErrorState, Input, Pagination } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import type { AdminApp } from './admin';
+import styles from './admin.module.scss';
+import { canOperate } from './crud';
+import { AdminFilterInvalidError } from './errors';
+import { FILTER_PREFIX } from './list-filters';
+import { CURSOR_PARAM } from './list-request';
+import { adminLookup } from './relations';
+import type { AdminResource } from './resource';
+import { type AdminScreen, framed, lookupHref, refused } from './screen-frame';
+
+const TERM_PARAM = 'term';
+const RETURN_PARAM = 'return';
+const AS_PARAM = 'as';
+const KNOWN: readonly string[] = [TERM_PARAM, CURSOR_PARAM, RETURN_PARAM, AS_PARAM];
+
+interface Asked {
+  readonly term: string;
+  readonly cursor: string | null;
+  /** The list to go back to, and the filter parameter to set on it. Both, or neither. */
+  readonly back: { readonly to: string; readonly as: string } | null;
+}
+
+/**
+ * What the URL asks for. `return` is followed by a link this screen renders, so it is held to the
+ * admin's own paths — an absolute URL or a `//host` here is somebody else's page wearing the
+ * admin's chrome — and `as` to a filter parameter, the only thing a lookup ever sets.
+ */
+function askedOf(app: AdminApp, resource: AdminResource, url: URL): Asked {
+  const refuse = (asked: string, cause: string): never => {
+    throw new AdminFilterInvalidError({ entity: resource.name, asked, cause, known: KNOWN });
+  };
+  for (const key of url.searchParams.keys()) {
+    if (!KNOWN.includes(key)) refuse(key, 'is not a parameter a lookup reads');
+  }
+  const to = url.searchParams.get(RETURN_PARAM) ?? '';
+  const as = url.searchParams.get(AS_PARAM) ?? '';
+  if ((to === '') !== (as === ''))
+    refuse(RETURN_PARAM, 'and `as` are given together or not at all');
+  if (to !== '' && !(to === app.basePath || to.startsWith(`${app.basePath}/`))) {
+    refuse(`${RETURN_PARAM}=${to}`, `is not a path under ${app.basePath}`);
+  }
+  if (as !== '' && !as.startsWith(FILTER_PREFIX)) {
+    refuse(`${AS_PARAM}=${as}`, `is not a filter parameter (${FILTER_PREFIX}<field>)`);
+  }
+  return {
+    term: url.searchParams.get(TERM_PARAM) ?? '',
+    cursor: url.searchParams.get(CURSOR_PARAM),
+    back: to === '' ? null : { to, as },
+  };
+}
+
+/** The list a result returns to, with the picked id set and the old page position dropped. */
+const picked = (back: { readonly to: string; readonly as: string }, id: string): string => {
+  const [path = '', search = ''] = back.to.split('?', 2);
+  const query = new URLSearchParams(search);
+  query.set(back.as, id);
+  query.delete(CURSOR_PARAM);
+  return `${path}?${query.toString()}`;
+};
+
+export function lookupScreen(app: AdminApp, resource: AdminResource): AdminScreen {
+  const here = lookupHref(app.basePath, resource);
+  return async (request) => {
+    const url = new URL(request.url);
+    // Decided before the URL is read: an actor who may not list the target learns nothing about
+    // which parameters its lookup takes.
+    if (!canOperate(resource, 'list', request.ctx)) {
+      const denied = await adminLookup(resource, request.ctx);
+      if (!denied.ok) return refused(app, request, resource.titleKey, denied.decision);
+    }
+    let asked: Asked;
+    try {
+      asked = askedOf(app, resource, url);
+    } catch (error) {
+      if (!(error instanceof AdminFilterInvalidError)) throw error;
+      return framed(app, request, resource.titleKey, <ErrorState error={error} />, 400);
+    }
+    const result = await adminLookup(resource, request.ctx, {
+      term: asked.term,
+      cursor: asked.cursor,
+    });
+    if (!result.ok) return refused(app, request, resource.titleKey, result.decision);
+
+    const state = (cursor: string | null): string => {
+      const query = new URLSearchParams();
+      if (asked.term !== '') query.set(TERM_PARAM, asked.term);
+      if (asked.back !== null) {
+        query.set(RETURN_PARAM, asked.back.to);
+        query.set(AS_PARAM, asked.back.as);
+      }
+      if (cursor !== null) query.set(CURSOR_PARAM, cursor);
+      const search = query.toString();
+      return search === '' ? here : `${here}?${search}`;
+    };
+    const hidden = (name: string, value: string): JSX.Element => (
+      <input type="hidden" name={name} value={value} />
+    );
+    const { page } = result;
+
+    return framed(
+      app,
+      request,
+      resource.titleKey,
+      <Card header={<h2>{t('admin.lookup.title', { entity: t(resource.titleKey) })}</h2>}>
+        <search>
+          <form class={styles['filters']} method="get" action={here}>
+            <Input
+              name={TERM_PARAM}
+              type="search"
+              value={asked.term}
+              aria-label={t('admin.search.label')}
+              placeholder={t('admin.lookup.placeholder')}
+            />
+            {asked.back === null ? null : hidden(RETURN_PARAM, asked.back.to)}
+            {asked.back === null ? null : hidden(AS_PARAM, asked.back.as)}
+            <Button type="submit" variant="secondary">
+              {t('admin.filter.apply')}
+            </Button>
+          </form>
+        </search>
+        {result.options.length === 0 ? (
+          <p class="x-admin-empty">{t('admin.list.empty')}</p>
+        ) : (
+          <ul class={styles['list']}>
+            {result.options.map((option) => (
+              <li>
+                <a
+                  href={
+                    asked.back === null
+                      ? `${app.basePath}${resource.path}/${option.id}`
+                      : picked(asked.back, option.id)
+                  }
+                >
+                  {option.label}
+                </a>{' '}
+                <span class={styles['mono']}>{option.id}</span>
+              </li>
+            ))}
+          </ul>
+        )}
+        <Pagination
+          nextCursor={page.hasMore ? (page.nextCursor ?? undefined) : undefined}
+          prevCursor={page.prevCursor ?? undefined}
+          hrefFor={(cursor) => state(cursor)}
+        />
+      </Card>,
+    );
+  };
+}