@ultimat3/admin 22.15.0 → 24.0.0

package/src/action-form.tsx

@@ -0,0 +1,139 @@
+// An action's own form: one control per property of its input schema, the confirmation a
+// destructive one needs, and the issues its schema raised against the fields that carried them.
+// A native `<form method="post">` at the row's URL (or the list's, for a batch) — the page ships
+// no script, so the round trip to the server IS the confirmation dialog.
+
+import { t } from '@ultimat3/i18n';
+import { Button, Card, Checkbox, Field, Input, Link, Select, Textarea } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import { ACTION_INPUT_PREFIX, type ActionInputField, actionInputFields } from './action-input';
+import { actionLabelKey } from './action-label';
+import { ConfirmationField, OPERATION_FIELD } from './actions';
+import styles from './admin.module.scss';
+import { issueText } from './form';
+import type { AdminAction } from './registry';
+import type { ValidationIssue } from './validate';
+
+export interface AdminActionFormProps {
+  readonly action: AdminAction;
+  /** Where the form posts: the row's URL, or the list's for a batch. */
+  readonly href: string;
+  /** `ACTION_OPERATION` for one row, `BATCH_OPERATION` for a selection. */
+  readonly operation: string;
+  /** What was typed, on a refused post. Empty on the first render. */
+  readonly values: Readonly<Record<string, string>>;
+  readonly issues: readonly ValidationIssue[];
+  /** The token a destructive action makes the operator type. `null`: not destructive. */
+  readonly confirmation: string | null;
+  /** One line above the fields saying what the action will run on — a row, or a count. */
+  readonly subject: string;
+  /** Posted back untouched: the selection of a batch, its filter position. */
+  readonly hidden?: readonly (readonly [name: string, value: string])[];
+  readonly cancelHref: string;
+}
+
+function control(
+  field: ActionInputField,
+  value: string | undefined,
+  shared: { readonly id: string; readonly 'aria-describedby': string | undefined },
+): JSX.Element {
+  const name = `${ACTION_INPUT_PREFIX}${field.name}`;
+  switch (field.control) {
+    case 'checkbox':
+      return (
+        <Checkbox
+          {...shared}
+          name={name}
+          label={t(field.labelKey)}
+          checked={value !== undefined && value !== 'false'}
+        />
+      );
+    case 'select':
+      return (
+        <Select
+          {...shared}
+          name={name}
+          value={value ?? ''}
+          options={[
+            ...(field.required ? [] : [{ value: '', label: t('admin.value.empty') }]),
+            ...field.values.map((one) => ({ value: one, label: one })),
+          ]}
+        />
+      );
+    case 'json':
+      return <Textarea {...shared} class="x-admin-json" name={name} value={value ?? ''} />;
+    case 'datetime':
+      // The stored value is a UTC instant, so the control edits UTC and says so beside the box.
+      return (
+        <Input {...shared} name={name} type="datetime-local" value={value ?? ''} suffix="UTC" />
+      );
+    case 'number':
+      // `inputmode` on a text field, never `type="number"`: the schema decides it is a number.
+      return <Input {...shared} name={name} inputmode="decimal" value={value ?? ''} />;
+    default:
+      return <Input {...shared} name={name} value={value ?? ''} />;
+  }
+}
+
+export function AdminActionForm(props: AdminActionFormProps): JSX.Element {
+  const labelKey = actionLabelKey(props.action);
+  const fields = actionInputFields(props.action);
+  // An issue the schema raised against no field of the form is still shown — at the top.
+  const loose = props.issues.filter((issue) => !fields.some((field) => field.name === issue.path));
+
+  return (
+    <Card header={<h2>{t(labelKey)}</h2>}>
+      <form class={styles['form']} method="post" action={props.href}>
+        <input type="hidden" name={OPERATION_FIELD} value={props.operation} />
+        <input type="hidden" name="name" value={props.action.name} />
+        {(props.hidden ?? []).map(([name, value]) => (
+          <input type="hidden" name={name} value={value} />
+        ))}
+        <p class={styles['note']}>{props.subject}</p>
+
+        {props.issues.length === 0 ? null : (
+          <div class="x-admin-issues" role="alert" tabindex={-1}>
+            <h3>{t('admin.form.issues')}</h3>
+            <ul>
+              {loose.map((issue) => (
+                <li>
+                  {issue.path === '' ? '' : `${issue.path}: `}
+                  {issueText(issue)}
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+
+        {fields.map((field) => {
+          const own = props.issues.filter((issue) => issue.path === field.name);
+          return (
+            <Field
+              label={t(field.labelKey)}
+              required={field.required && field.control !== 'checkbox'}
+              error={own.length === 0 ? undefined : own.map(issueText).join(' ')}
+            >
+              {(shared) =>
+                control(field, props.values[field.name], {
+                  id: shared.id,
+                  'aria-describedby': shared['aria-describedby'],
+                })
+              }
+            </Field>
+          );
+        })}
+
+        {props.confirmation === null ? null : <ConfirmationField token={props.confirmation} />}
+
+        <div class={styles['actions']}>
+          <Button type="submit" tone={props.action.destructive === true ? 'danger' : undefined}>
+            {t(labelKey)}
+          </Button>
+          <Link appearance="button" variant="ghost" tone="neutral" href={props.cancelHref}>
+            {t('admin.form.cancel')}
+          </Link>
+        </div>
+      </form>
+    </Card>
+  );
+}

package/src/action-gate.ts

@@ -3,6 +3,7 @@
 // authz, so a button that renders is a call that is allowed and a call that is denied had no
 // button. The admin's whole authz story is this file plus authz.ts.
 
+import { actionLabelKey } from './action-label';
 import { type AuditEntry, type AuditFieldDiff, type AuditLog, deniedDraft } from './audit';
 import {
   type AdminActor,
@@ -11,13 +12,16 @@ import {
   type AdminSubject,
   decideAll,
 } from './authz';
+import { atomicallyAudited } from './crud-outcome';
+import { AdminActionNotApplicableError } from './errors';
 import {
   ADMIN_DESTROY,
   ADMIN_WRITE,
   CONFIRMATION_REQUIRED_REASON,
   confirmationToken,
 } from './permissions';
-import type { AdminAction, AdminActionCtx } from './registry';
+import { type AdminAction, type AdminActionCtx, type AdminRow, computedRow } from './registry';
+import { type ValidationIssue, validateInput } from './validate';
 
 export interface AdminActionButton {
   readonly name: string;
@@ -25,6 +29,8 @@ export interface AdminActionButton {
   readonly destructive: boolean;
   readonly permission: string;
   readonly entity: string | null;
+  /** The action declares an input schema: its control is a link to its form, never a bare post. */
+  readonly form: boolean;
   /** Carried so the `/_x` policy panel can show why this button is on screen. */
   readonly decision: AdminDecision;
 }
@@ -35,6 +41,12 @@ export interface AdminActionButton {
  */
 const ACTION_FAILED_REASON = 'admin.error.action-failed';
 
+/** The reason an action refused by its own `when()` is answered and audited with. */
+export const ACTION_NOT_APPLICABLE_REASON = 'admin.error.action-not-applicable';
+
+/** The reason an action whose input its own schema refused is audited with. */
+const ACTION_INVALID_REASON = 'admin.error.invalid-input';
+
 /** The permissions an action needs: the admin-level gate, then the action's own policy. */
 export function permissionsForAction<Input, Output>(
   action: AdminAction<Input, Output>,
@@ -56,6 +68,37 @@ export interface ActionGateInput {
   readonly actor: AdminActor;
   readonly authz: AdminAuthz;
   readonly subject?: AdminSubject;
+  /** The resource's sealed column names: dropped from the row a `when` is handed. */
+  readonly sealed?: readonly string[];
+}
+
+const isRow = (value: unknown): value is AdminRow => typeof value === 'object' && value !== null;
+
+/**
+ * Whether `action` applies to the subject's row — the ONE evaluation of `when`, asked by the
+ * button and by the call behind it.
+ *
+ * A subject with no row at all (`undefined`: a toolbar, a batch bar) is not a row to refuse. A row
+ * that was looked for and not found (`null`) is refused, `when` or none — an action on a row is an
+ * action on THAT row, and a row the actor's scope leaves out is not there. No `when`: any row
+ * applies. A `when` that throws is a refusal too: the rule did not say yes.
+ */
+export function actionApplies<Input, Output>(
+  action: AdminAction<Input, Output>,
+  subject: AdminSubject | undefined,
+  sealed: readonly string[] = [],
+): boolean {
+  if (subject === undefined || subject.row === undefined) return true;
+  // Looked for and not there — or outside the actor's `rows` — is refused for EVERY action, not
+  // only one that declares `when`: an action with no rule about a row's state still acts on a row,
+  // and running its handler on an id the actor cannot see was a way round the row scope.
+  if (!isRow(subject.row)) return false;
+  if (action.when === undefined) return true;
+  try {
+    return action.when(computedRow(subject.row, sealed)) === true;
+  } catch {
+    return false;
+  }
 }
 
 /** Every action with its decision — what the `/_x` policy panel and tests want to see. */
@@ -68,16 +111,21 @@ export function actionDecisions(
   }));
 }
 
-/** Only the buttons this actor may press. A denied action has no button, ever. */
+/**
+ * Only the buttons this actor may press ON THIS ROW. A denied action has no button, ever, and
+ * neither has one whose `when` excludes the row.
+ */
 export function actionButtons(input: ActionGateInput): readonly AdminActionButton[] {
   return actionDecisions(input)
     .filter(({ decision }) => decision.allowed)
+    .filter(({ action }) => actionApplies(action, input.subject, input.sealed))
     .map(({ action, decision }) => ({
       name: action.name,
-      labelKey: action.labelKey ?? `admin.action.${action.name}`,
+      labelKey: actionLabelKey(action),
       destructive: action.destructive === true,
       permission: action.permission,
       entity: action.entity ?? null,
+      form: action.input !== undefined,
       decision,
     }));
 }
@@ -86,9 +134,25 @@ export type InvokeResult<Output> =
   | { readonly ok: true; readonly value: Output; readonly audit: AuditEntry }
   | {
       readonly ok: false;
+      readonly kind: 'denied';
       readonly decision: AdminDecision;
       readonly confirmationRequired: boolean;
       readonly audit: AuditEntry;
+    }
+  /** The action's `when()` excludes the row. `error` is `X_ADMIN_ACTION_NOT_APPLICABLE`. */
+  | {
+      readonly ok: false;
+      readonly kind: 'not-applicable';
+      readonly decision: AdminDecision;
+      readonly error: AdminActionNotApplicableError;
+      readonly audit: AuditEntry;
+    }
+  /** The action's own input schema refused what was sent: one issue per field. */
+  | {
+      readonly ok: false;
+      readonly kind: 'invalid';
+      readonly issues: readonly ValidationIssue[];
+      readonly audit: AuditEntry;
     };
 
 export interface InvokeInput<Input, Output> {
@@ -99,6 +163,8 @@ export interface InvokeInput<Input, Output> {
   readonly audit: AuditLog;
   readonly requestId: string;
   readonly subject?: AdminSubject;
+  /** The resource's sealed column names: dropped from the row a `when` is handed. */
+  readonly sealed?: readonly string[];
   /**
    * Echo of `confirmationToken(entity, subject.id)`. Required for a destructive action, and the
    * gate DERIVES the token it compares against — it took the caller's `expectedConfirmation`
@@ -116,8 +182,10 @@ export interface InvokeInput<Input, Output> {
 }
 
 /**
- * Run an admin action. The policy is consulted first, the confirmation second, the handler
- * last, and all three outcomes are audited before this function returns.
+ * Run an admin action on one subject. In this order: the policy, the action's own `when()` over
+ * the row as it is now, the confirmation, the action's input schema, the handler — and every one
+ * of the five outcomes is audited before this function returns. The button, the batch bar and the
+ * MCP tool all end here, so there is one ordering of those steps and not one per surface.
  */
 export async function invokeAdminAction<Input, Output>(
   args: InvokeInput<Input, Output>,
@@ -127,22 +195,40 @@ export async function invokeAdminAction<Input, Output>(
   const entityId = args.subject?.id ?? null;
   const decision = decideAction(action, actor, authz, args.subject);
 
+  const entry = {
+    requestId,
+    actor,
+    operation: action.name,
+    kind: 'action',
+    entity,
+    entityId,
+  } as const;
+
   if (!decision.allowed) {
     return {
       ok: false,
+      kind: 'denied',
       decision,
       confirmationRequired: false,
-      audit: await audit.append(
-        deniedDraft({
-          requestId,
-          actor,
-          operation: action.name,
-          kind: 'action',
-          entity,
-          entityId,
-          decision,
-        }),
-      ),
+      audit: await audit.append(deniedDraft({ ...entry, decision })),
+    };
+  }
+
+  // After the grant, before anything else: the same `when` that decided the button, asked of the
+  // row as it is NOW. A hidden button is not an authorization.
+  if (!actionApplies(action, args.subject, args.sealed)) {
+    const refused: AdminDecision = {
+      allowed: false,
+      permission: action.permission,
+      reason: ACTION_NOT_APPLICABLE_REASON,
+      trace: [`when: ${action.name} does not apply to ${entity} ${entityId ?? '(no row)'}`],
+    };
+    return {
+      ok: false,
+      kind: 'not-applicable',
+      decision: refused,
+      error: new AdminActionNotApplicableError({ action: action.name, entity, id: entityId }),
+      audit: await audit.append(deniedDraft({ ...entry, decision: refused })),
     };
   }
 
@@ -156,22 +242,36 @@ export async function invokeAdminAction<Input, Output>(
     };
     return {
       ok: false,
+      kind: 'denied',
       decision: refused,
       confirmationRequired: true,
-      audit: await audit.append(
-        deniedDraft({
-          requestId,
-          actor,
-          operation: action.name,
-          kind: 'action',
-          entity,
-          entityId,
-          decision: refused,
-        }),
-      ),
+      audit: await audit.append(deniedDraft({ ...entry, decision: refused })),
     };
   }
 
+  // The action's own schema judges its own input. The row's `id` is the admin's envelope and is
+  // no property of that schema, so it rides around the parse and is put back for the handler.
+  let input = args.input;
+  if (action.input !== undefined) {
+    const { id, ...own } = { ...(args.input as Readonly<Record<string, unknown>>) };
+    const parsed = await validateInput(action.input, own);
+    if (!parsed.ok) {
+      return {
+        ok: false,
+        kind: 'invalid',
+        issues: parsed.issues,
+        audit: await audit.append({
+          ...entry,
+          permission: action.permission,
+          outcome: 'failed',
+          reason: ACTION_INVALID_REASON,
+          diff: [],
+        }),
+      };
+    }
+    input = { ...parsed.value, ...(id === undefined ? {} : { id }) } as Input;
+  }
+
   const ctx: AdminActionCtx = {
     requestId,
     actorId: actor.id,
@@ -179,51 +279,24 @@ export async function invokeAdminAction<Input, Output>(
     timeZone: args.timeZone ?? actor.timeZone ?? 'UTC',
   };
 
-  try {
-    const value = await action.handle({ input: args.input, ctx });
-    return {
-      ok: true,
-      value,
-      audit: await audit.append({
-        requestId,
-        actor,
-        operation: action.name,
-        kind: 'action',
-        entity,
-        entityId,
-        permission: action.permission,
-        outcome: 'allowed',
-        reason: decision.reason,
-        diff: args.diff ?? [],
-      }),
-    };
-  } catch (error) {
-    // NOTHING is read off `error` before the append, and nothing is read off it at all.
-    //
-    // This built an `AdminDecision` first, whose `trace` rendered the caught value with
-    // `String(error)` — and a `catch` binding is annotated by nobody, so it holds whatever an
-    // app's handler threw. `Object.create(null)` has no `toString`, no `valueOf` and no
-    // `Symbol.toPrimitive`, so `String(it)` raises `TypeError: No default value` from inside the
-    // block that owes the auditor an entry: measured, ZERO entries, and the caller received the
-    // TypeError instead of what was thrown. Ordering was the second half — the render ran BEFORE
-    // `append`, so its throw skipped the append rather than merely spoiling one field.
-    //
-    // The decision object was also DEAD: only its `reason` was ever read, and `append` takes no
-    // trace. So there is no destination for a rendered value here and `renderThrowable` is not
-    // needed either — an audit reason is a key the view renders, never a sentence from a
-    // database, an upstream or an attacker.
-    await audit.append({
+  // The handler and its entry are ONE unit (`atomicallyAudited`): a handler whose writes ride the
+  // ambient transaction commits with its `allowed` entry or not at all, and a throw from either
+  // leaves exactly one `failed` entry, appended after the rollback, with nothing read off the
+  // thrown value — which reaches the caller unchanged.
+  const { value, audit: appended } = await atomicallyAudited(
+    audit,
+    {
       requestId,
       actor,
       operation: action.name,
       kind: 'action',
       entity,
-      entityId,
       permission: action.permission,
-      outcome: 'failed',
-      reason: ACTION_FAILED_REASON,
-      diff: [],
-    });
-    throw error;
-  }
+    },
+    { allowed: decision.reason, failed: ACTION_FAILED_REASON },
+    entityId,
+    () => action.handle({ input, ctx }),
+    () => ({ entityId, diff: args.diff ?? [] }),
+  );
+  return { ok: true, value, audit: appended };
 }

package/src/action-input.ts

@@ -0,0 +1,119 @@
+// An action's input schema, as the form it renders and the posted strings it reads back. The
+// schema is the action's own (`t.object({ … })`); this file reads its introspectable node — the
+// one IR OpenAPI, MCP and HTTP coercion read — and never writes a second description of it.
+
+import { coerceNode, requiredKeys, type SchemaNode, tryIntrospect } from '@ultimat3/schema';
+import { posted } from './form-decode';
+import type { AdminAction } from './registry';
+
+/** A posted action input is `input.<property>`: the envelope's own names can never collide. */
+export const ACTION_INPUT_PREFIX = 'input.';
+
+/** The control one property of an action's input is drawn as. */
+export type ActionInputControl = 'text' | 'number' | 'checkbox' | 'select' | 'datetime' | 'json';
+
+export interface ActionInputField {
+  readonly name: string;
+  /** `admin.input.<action>.<name>` — beside the action's own label key, never under it. */
+  readonly labelKey: string;
+  readonly control: ActionInputControl;
+  readonly required: boolean;
+  /** The closed set of a `select`. */
+  readonly values: readonly string[];
+  readonly node: SchemaNode;
+}
+
+const controlOf = (node: SchemaNode): ActionInputControl => {
+  switch (node.kind) {
+    case 'string':
+      return node.format === 'date-time' ? 'datetime' : 'text';
+    case 'number':
+      return 'number';
+    case 'boolean':
+      return 'checkbox';
+    case 'enum':
+      return 'select';
+    case 'date':
+      return 'datetime';
+    default:
+      // An object, a list, a union, money: typed as JSON and judged by the schema.
+      return 'json';
+  }
+};
+
+/**
+ * The fields of an action's form, in the schema's own property order. Empty for an action with no
+ * input schema and for a schema that is not an introspectable object — such an action's button is
+ * a confirm, and its schema still judges whatever a caller sends.
+ */
+export function actionInputFields(
+  action: Pick<AdminAction, 'name' | 'input'>,
+): readonly ActionInputField[] {
+  const node = tryIntrospect(action.input);
+  if (node === undefined || node.kind !== 'object' || node.properties === undefined) return [];
+  const required = requiredKeys(node);
+  return Object.entries(node.properties).map(([name, property]) => ({
+    name,
+    // Under `admin.input`, never under the action's own `admin.action.<name>`: a JSON catalog is
+    // a tree, so the action's label (a leaf) could not also hold its fields (a branch).
+    labelKey: `admin.input.${action.name}.${name}`,
+    control: controlOf(property),
+    required: required.includes(name),
+    values: (property.values ?? []).map(String),
+    node: property,
+  }));
+}
+
+const LOCAL_MINUTE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/;
+
+const jsonOf = (raw: string): unknown => {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    // Left as typed: the schema names the field, which a thrown SyntaxError would not.
+    return raw;
+  }
+};
+
+/**
+ * The posted form → the input the action's schema judges. Converts and never validates: a value
+ * that will not convert is passed through as typed, so the schema refuses it in its own words
+ * against the field that carried it. An empty box of an optional field is absent, never `''`.
+ */
+export function decodeActionInput(
+  action: Pick<AdminAction, 'name' | 'input'>,
+  form: Readonly<Record<string, unknown>>,
+): Readonly<Record<string, unknown>> {
+  const out: Record<string, unknown> = {};
+  for (const field of actionInputFields(action)) {
+    const raw = posted(form, `${ACTION_INPUT_PREFIX}${field.name}`);
+    // An unchecked box posts nothing at all, so absence IS the answer for a checkbox.
+    if (field.control === 'checkbox') {
+      out[field.name] = raw !== undefined && raw !== 'false';
+      continue;
+    }
+    if (raw === undefined || raw === '') {
+      if (field.required && field.control === 'text') out[field.name] = '';
+      continue;
+    }
+    if (field.control === 'json') out[field.name] = jsonOf(raw);
+    // `datetime-local` posts `YYYY-MM-DDTHH:mm`, and the control says UTC beside the box.
+    else if (field.control === 'datetime' && LOCAL_MINUTE.test(raw)) {
+      out[field.name] = coerceNode(field.node, `${raw}:00.000Z`);
+    } else out[field.name] = coerceNode(field.node, raw);
+  }
+  return out;
+}
+
+/** What a refused form shows again: the strings that were typed, by field. */
+export function postedActionInput(
+  action: Pick<AdminAction, 'name' | 'input'>,
+  form: Readonly<Record<string, unknown>>,
+): Readonly<Record<string, string>> {
+  const out: Record<string, string> = {};
+  for (const field of actionInputFields(action)) {
+    const raw = posted(form, `${ACTION_INPUT_PREFIX}${field.name}`);
+    if (raw !== undefined) out[field.name] = raw;
+  }
+  return out;
+}

package/src/action-label.ts

@@ -0,0 +1,9 @@
+// An action's label key, spelled once. The button, its form, the batch bar, the batch result and
+// `catalogKeys()` all read it here, so the key a screen draws and the key the `i18n` step asks a
+// catalog for cannot be two spellings of one rule.
+
+import type { AdminAction } from './registry';
+
+/** `labelKey` when the action names one, else `admin.action.<name>` — its MCP tool's name too. */
+export const actionLabelKey = (action: Pick<AdminAction, 'name' | 'labelKey'>): string =>
+  action.labelKey ?? `admin.action.${action.name}`;

package/src/action-row.ts

@@ -0,0 +1,37 @@
+// One action on ONE row of a resource: the row is loaded through the row scope, and the gate
+// decides on it. The detail page's button, each row of a batch and the MCP tool all call this, so
+// "which row did the rule see" has one answer and a row outside `rows(actor)` is no row at all.
+
+import { type InvokeResult, invokeAdminAction } from './action-gate';
+import type { CrudCtx } from './crud';
+import { findRow } from './list-scope';
+import type { AdminAction } from './registry';
+import type { AdminResource } from './resource';
+
+export interface RowActionInput {
+  readonly resource: AdminResource;
+  readonly action: AdminAction;
+  readonly id: string;
+  readonly ctx: CrudCtx;
+  /** The action's own input, already decoded. The row's `id` is added here. */
+  readonly input?: Readonly<Record<string, unknown>>;
+  readonly confirmation?: string | undefined;
+}
+
+export async function invokeRowAction(args: RowActionInput): Promise<InvokeResult<unknown>> {
+  const { resource, action, id, ctx } = args;
+  // Loaded before the guard, the shape `adminDetail` uses: a rule that decides about a row cannot
+  // decide without one — and neither can the action's own `when`.
+  const row = await findRow(resource, ctx.actor, id);
+  return invokeAdminAction({
+    action,
+    input: { ...(args.input ?? {}), id },
+    actor: ctx.actor,
+    authz: ctx.authz,
+    audit: ctx.audit,
+    requestId: ctx.requestId,
+    subject: { entity: resource.name, id, row },
+    sealed: resource.secretFields.map((field) => field.name),
+    ...(args.confirmation === undefined ? {} : { confirmation: args.confirmation }),
+  });
+}