@ultimat3/admin 22.14.0 → 23.0.0

package/src/audit.ts

@@ -24,7 +24,12 @@ export interface AuditEntry {
   /** ISO-8601 UTC. Stored UTC, formatted per viewer zone at the edge. */
   readonly at: string;
   readonly requestId: string;
-  readonly actor: { readonly id: string; readonly roles: readonly string[] };
+  readonly actor: {
+    readonly id: string;
+    readonly roles: readonly string[];
+    /** The tenant the actor acted under. Absent for a single-tenant app. */
+    readonly orgId?: string;
+  };
   /** `list` | `create` | `update` | `delete`, or an action name. */
   readonly operation: string;
   readonly kind: 'operation' | 'action';
@@ -50,19 +55,49 @@ export interface AuditDraft {
   readonly diff?: readonly AuditFieldDiff[];
 }
 
-/** Where entries go beyond memory: a table, stdout as JSON lines, an OTel log. */
+/** Where a copy of every entry goes besides the log's own store: stdout as JSON lines, OTel. */
 export interface AuditSink {
   write(entry: AuditEntry): Promise<void> | void;
 }
 
+/** A position in the trail: the entry a page ended on. Entries are ordered `at` then `id`. */
+export interface AuditCursor {
+  readonly at: string;
+  readonly id: string;
+}
+
+export interface AuditQuery {
+  readonly entity?: string;
+  /** One row's trail — what the detail page's history card asks, with `entity`. */
+  readonly entityId?: string;
+  readonly actorId?: string;
+  /** Only entries written by an actor of this tenant. */
+  readonly orgId?: string;
+  readonly limit?: number;
+  /** Keyset: only entries strictly OLDER than this one. There is no offset. */
+  readonly before?: AuditCursor;
+  /**
+   * Leave out the reads that were allowed — `list`, `detail`, `search`, a page — and keep what
+   * changed something or was refused. What a row's history shows.
+   */
+  readonly changes?: boolean;
+}
+
 export interface AuditLog {
   append(draft: AuditDraft): Promise<AuditEntry>;
-  /** Newest first. A copy — the log cannot be mutated through what it hands out. */
-  entries(query?: {
-    readonly entity?: string;
-    readonly actorId?: string;
-    readonly limit?: number;
-  }): readonly AuditEntry[];
+  /**
+   * Newest first, at most `limit` (`AUDIT_PAGE_MAX` at the outside). A copy — the log cannot be
+   * mutated through what it hands out. Async because the record is a table, not this process.
+   */
+  entries(query?: AuditQuery): Promise<readonly AuditEntry[]>;
+  /**
+   * Run a write and its entry as ONE unit where the store can: a durable log opens a transaction,
+   * so a row never changes without its entry and an entry never names a write that rolled back.
+   * The memory log has nothing to join and runs `run` as it is.
+   */
+  atomic<T>(run: () => Promise<T>): Promise<T>;
+  /** `memory`, `postgres`, or an app's own word. What the manifest records about this admin. */
+  readonly kind: string;
 }
 
 export interface AuditLogOptions {
@@ -74,12 +109,52 @@ export interface AuditLogOptions {
   readonly capacity?: number;
 }
 
+/** The most entries one read answers, whatever it asked for. */
+export const AUDIT_PAGE_MAX = 200;
+
+/** What a read answers when it names no limit. */
+export const AUDIT_PAGE_DEFAULT = 100;
+
+/** The operations that only LOOK. An allowed one is a read; a refused one is still an event. */
+export const AUDIT_READ_OPERATIONS: readonly string[] = ['list', 'detail', 'search', 'page'];
+
+/** An entry that changed nothing and was refused nothing — the only kind `changes` leaves out. */
+export const isAllowedRead = (entry: AuditEntry): boolean =>
+  entry.kind === 'operation' &&
+  entry.outcome === 'allowed' &&
+  AUDIT_READ_OPERATIONS.includes(entry.operation);
+
+/** The page size a query asks for, bounded. Refused when it is not a count at all. */
+export const auditLimit = (subject: string, query: AuditQuery): number =>
+  Math.min(
+    AUDIT_PAGE_MAX,
+    query.limit === undefined
+      ? AUDIT_PAGE_DEFAULT
+      : // `slice(0, NaN)` is `[]`: an unreadable limit would answer "nothing was ever logged".
+        // 0 stays legal — asking for none is a coherent request.
+        finiteCount(subject, 'entries limit', query.limit),
+  );
+
+/** Where the page after `entries` starts, or `null` for an empty page. */
+export const auditCursorOf = (entries: readonly AuditEntry[]): AuditCursor | null => {
+  const last = entries[entries.length - 1];
+  return last === undefined ? null : { at: last.at, id: last.id };
+};
+
+/** `-1` when `a` is NEWER than `b`: the trail's one order, `at` then `id`, both descending. */
+const newestFirst = (a: AuditCursor, b: AuditCursor): number =>
+  a.at === b.at ? (a.id === b.id ? 0 : a.id > b.id ? -1 : 1) : a.at > b.at ? -1 : 1;
+
 export function auditEntry(draft: AuditDraft, id: string, at: Date): AuditEntry {
   return {
     id,
     at: at.toISOString(),
     requestId: draft.requestId,
-    actor: { id: draft.actor.id, roles: draft.actor.roles ?? [] },
+    actor: {
+      id: draft.actor.id,
+      roles: draft.actor.roles ?? [],
+      ...(draft.actor.orgId === undefined ? {} : { orgId: draft.actor.orgId }),
+    },
     operation: draft.operation,
     kind: draft.kind,
     entity: draft.entity,
@@ -102,6 +177,7 @@ export function memoryAuditLog(opts: AuditLogOptions = {}): AuditLog {
   const log: AuditEntry[] = [];
 
   return {
+    kind: 'memory',
     async append(draft: AuditDraft): Promise<AuditEntry> {
       // Timestamp first: the entry is stamped when it happened, not when the id generator
       // got around to it.
@@ -112,20 +188,31 @@ export function memoryAuditLog(opts: AuditLogOptions = {}): AuditLog {
       for (const sink of sinks) await sink.write(entry);
       return entry;
     },
-    entries(query = {}): readonly AuditEntry[] {
-      const filtered = log.filter(
-        (entry) =>
-          (query.entity === undefined || entry.entity === query.entity) &&
-          (query.actorId === undefined || entry.actor.id === query.actorId),
-      );
-      const newestFirst = [...filtered].reverse();
-      // The opposite failure to `capacity`, from the same missing check: `slice(0, NaN)` is `[]`,
-      // so an unreadable limit answers "nothing was ever logged" and reads as a successful read.
-      // 0 stays legal — asking for none is a coherent request.
-      return query.limit === undefined
-        ? newestFirst
-        : newestFirst.slice(0, finiteCount(SUBJECT, 'entries limit', query.limit));
+    async entries(query = {}): Promise<readonly AuditEntry[]> {
+      const limit = auditLimit(SUBJECT, query);
+      const before = query.before;
+      // Insertion order reversed IS newest first, ties included: two entries of one millisecond
+      // read in the order they were written, which an id drawn at random could not promise.
+      const at = before === undefined ? -1 : log.findIndex((entry) => entry.id === before.id);
+      const older =
+        before === undefined
+          ? log
+          : at >= 0
+            ? log.slice(0, at)
+            : log.filter((entry) => newestFirst(before, entry) < 0);
+      return older
+        .filter(
+          (entry) =>
+            (query.entity === undefined || entry.entity === query.entity) &&
+            (query.entityId === undefined || entry.entityId === query.entityId) &&
+            (query.actorId === undefined || entry.actor.id === query.actorId) &&
+            (query.orgId === undefined || entry.actor.orgId === query.orgId) &&
+            (query.changes !== true || !isAllowedRead(entry)),
+        )
+        .reverse()
+        .slice(0, limit);
     },
+    atomic: (run) => run(),
   };
 }
 

package/src/authz.ts

@@ -147,6 +147,17 @@ export function expandPermissions(granted: readonly string[]): readonly string[]
   return [...out].sort();
 }
 
+/**
+ * The admin permissions whose grant carries `permission` — `admin:write` is carried by
+ * `admin:destroy`. The inverse of `expandPermissions`, so an authz that decides one name at a time
+ * (`roleAuthz`) answers exactly what a grant-list authz answers for the same grants.
+ */
+export function impliersOf(permission: string): readonly string[] {
+  return Object.keys(ADMIN_PERMISSION_SPEC).filter(
+    (candidate) => candidate !== permission && expandPermissions([candidate]).includes(permission),
+  );
+}
+
 /**
  * A grant-list authz for tests, seeds, and `x dev --actor`. Production always goes through
  * `policyAuthz()` so the app's real rules (ownership, org scoping) are the ones evaluated.

package/src/batch-bar.tsx

@@ -0,0 +1,66 @@
+// The list's batch bar: one native form posted at the LIST's own URL — whose query string is the
+// filter "all matching" means — holding which action, over which rows, and the submit. The row
+// checkboxes sit in the table and join this form through their `form` attribute, because a form
+// cannot hold a table that already holds the filter bar's. No script: selection is a checkbox,
+// "every row this filter matches" is a radio, and the server answers with what it did.
+
+import { t } from '@ultimat3/i18n';
+import { Button, Checkbox, Radio, Select } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import { actionLabelKey } from './action-label';
+import { BATCH_OPERATION, OPERATION_FIELD } from './actions';
+import styles from './admin.module.scss';
+import type { AdminAction } from './registry';
+
+/** The id of the batch form, which every row checkbox names in its `form` attribute. */
+export const BATCH_FORM_ID = 'x-admin-batch';
+
+/** The posted field each checked row's id rides in; repeated once per row. */
+export const BATCH_IDS_FIELD = 'ids';
+
+/** `checked` (the default) or `all` — every row the list's scope and filters match. */
+export const BATCH_SELECTION_FIELD = 'selection';
+
+export interface AdminBatchBarProps {
+  /** The batch actions this actor may run on this resource — decided by the caller's gate. */
+  readonly actions: readonly AdminAction[];
+  /** The list's URL in its current state: the form posts here. */
+  readonly href: string;
+}
+
+export function AdminBatchBar(props: AdminBatchBarProps): JSX.Element {
+  if (props.actions.length === 0) return <span class="x-admin-batch-empty" />;
+  return (
+    <form id={BATCH_FORM_ID} class={styles['batch']} method="post" action={props.href}>
+      <input type="hidden" name={OPERATION_FIELD} value={BATCH_OPERATION} />
+      <Select
+        name="name"
+        aria-label={t('admin.batch.action')}
+        options={props.actions.map((action) => ({
+          value: action.name,
+          label: t(actionLabelKey(action)),
+        }))}
+      />
+      <Radio
+        legend={t('admin.batch.over')}
+        name={BATCH_SELECTION_FIELD}
+        direction="row"
+        value="checked"
+        options={[
+          { value: 'checked', label: t('admin.batch.checked') },
+          { value: 'all', label: t('admin.batch.all') },
+        ]}
+      />
+      <Button type="submit" size="sm" variant="secondary">
+        {t('admin.batch.run')}
+      </Button>
+    </form>
+  );
+}
+
+/** One row's checkbox, joined to the batch form by its id. */
+export function BatchCheckbox(props: { readonly id: string; readonly label: string }): JSX.Element {
+  return (
+    <Checkbox form={BATCH_FORM_ID} name={BATCH_IDS_FIELD} value={props.id} label={props.label} />
+  );
+}

package/src/batch-job.ts

@@ -0,0 +1,152 @@
+// The queued half of a batch: ONE framework job, `admin.batch`, that runs one chunk of a batch
+// past its declared threshold through the same per-row gate an inline batch uses. A job and not a
+// ninth kind of thing — `enqueue` and a declaration are all it uses of `@ultimat3/jobs`.
+
+import { userActor, withChildContext } from '@ultimat3/core';
+import { type AnyJobHandle, getJob, job, t } from '@ultimat3/jobs';
+import type { AdminActor } from './authz';
+import { type BatchEnqueue, type BatchRow, runBatchRows } from './batch';
+import { AdminMountMissingError } from './errors';
+import { jsonText } from './json-text';
+import { adminMountAt, adminMounts } from './mounts';
+
+/** The queued input text, back to an object. Anything else is no input, which the schema judges. */
+const inputOf = (text: string): Readonly<Record<string, unknown>> => {
+  try {
+    const value: unknown = JSON.parse(text);
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+      ? (value as Readonly<Record<string, unknown>>)
+      : {};
+  } catch {
+    return {};
+  }
+};
+
+/** The job's durable name: the queue key every queued chunk carries. Never renamed. */
+export const ADMIN_BATCH_JOB = 'admin.batch';
+
+const chunkInput = t.object({
+  basePath: t.string,
+  entity: t.string,
+  action: t.string,
+  ids: t.array(t.string),
+  // The action's input as JSON text: the action's own schema judges it again on the worker, so
+  // the queue carries no second description of a contract this package does not own.
+  input: t.string,
+  batchId: t.string,
+  index: t.number.int(),
+  requestId: t.string,
+  actor: t.object({
+    id: t.string,
+    roles: t.array(t.string),
+    orgId: t.optional(t.string),
+    locale: t.optional(t.string),
+    timeZone: t.optional(t.string),
+  }),
+});
+
+export interface AdminBatchChunk {
+  readonly basePath: string;
+  readonly entity: string;
+  readonly action: string;
+  readonly ids: readonly string[];
+  /** `jsonText` of the validated input. */
+  readonly input: string;
+  readonly batchId: string;
+  readonly index: number;
+  readonly requestId: string;
+  readonly actor: {
+    readonly id: string;
+    readonly roles: readonly string[];
+    readonly orgId?: string | undefined;
+    readonly locale?: string | undefined;
+    readonly timeZone?: string | undefined;
+  };
+}
+
+/**
+ * Run one chunk: find the admin it was queued from, and every row through the gate AS the
+ * operator who queued it — their roles decide, their tenant scopes every read. Nothing about the
+ * operator is trusted beyond what the queue row carries, which only the server wrote.
+ */
+export async function runBatchChunk(chunk: AdminBatchChunk): Promise<readonly BatchRow[]> {
+  const app = adminMountAt(chunk.basePath);
+  if (app === undefined) {
+    throw new AdminMountMissingError({
+      basePath: chunk.basePath,
+      mounted: adminMounts().map((one) => one.basePath),
+    });
+  }
+  const resource = app.resource(chunk.entity);
+  const action = resource.actions.find((declared) => declared.name === chunk.action);
+  // An action renamed or removed between the enqueue and the claim has nothing to run: every row
+  // is refused by the gate's own answer for an action this resource does not declare.
+  if (action === undefined) {
+    return chunk.ids.map((id) => ({ id, outcome: 'refused', reason: 'admin.actions.unknown' }));
+  }
+  const actor: AdminActor = {
+    id: chunk.actor.id,
+    roles: chunk.actor.roles,
+    ...(chunk.actor.orgId === undefined ? {} : { orgId: chunk.actor.orgId }),
+    ...(chunk.actor.locale === undefined ? {} : { locale: chunk.actor.locale }),
+    ...(chunk.actor.timeZone === undefined ? {} : { timeZone: chunk.actor.timeZone }),
+  };
+  const ctx = app.ctx({ actor, requestId: chunk.requestId });
+  // The operator is the ambient actor too, tenant included — what the entity's tenant guard
+  // reads — exactly as `mcp.ts` installs an agent for its call.
+  return withChildContext(
+    {
+      actor: userActor({
+        id: actor.id,
+        roles: [...(actor.roles ?? [])],
+        ...(actor.orgId === undefined ? {} : { orgId: actor.orgId }),
+      }),
+    },
+    () => runBatchRows({ resource, action, ctx, ids: chunk.ids, input: inputOf(chunk.input) }),
+  );
+}
+
+/**
+ * The job, declared on first use and once per process. `tenant: 'none'` because the TENANT is
+ * the operator's and the body installs it (`runBatchChunk`); a chunk is one attempt — a handler
+ * that half-ran is not one to re-run, and every row it reached is already on the audit log.
+ */
+export function adminBatchJob(): AnyJobHandle {
+  const seated = getJob(ADMIN_BATCH_JOB);
+  if (seated !== undefined) return seated;
+  return job({
+    name: ADMIN_BATCH_JOB,
+    input: chunkInput,
+    idempotencyKey: (chunk) => `${ADMIN_BATCH_JOB}:${chunk.batchId}:${String(chunk.index)}`,
+    tenant: 'none',
+    retry: { attempts: 1, backoff: 'fixed' },
+    // A chunk's input is the server's own, written by `batchEnqueue` below: parsed, never trusted
+    // past what it names — the rows are decided again, one by one, on the worker.
+    run: ({ input }) => runBatchChunk(input),
+  }) as AnyJobHandle;
+}
+
+/** What `runAdminBatch` queues a chunk with: one `admin.batch` job, its id answered. */
+export const batchEnqueue =
+  (basePath: string): BatchEnqueue =>
+  async (chunk) => {
+    const actor = chunk.ctx.actor;
+    const queued = await adminBatchJob().enqueue({
+      basePath,
+      entity: chunk.resource.name,
+      action: chunk.action.name,
+      ids: [...chunk.ids],
+      input: jsonText(chunk.input),
+      batchId: chunk.batchId,
+      index: chunk.index,
+      requestId: chunk.ctx.requestId,
+      actor: {
+        id: actor.id,
+        roles: [...(actor.roles ?? [])],
+        ...(actor.orgId === undefined ? {} : { orgId: actor.orgId }),
+        ...(actor.locale === undefined ? {} : { locale: actor.locale }),
+        ...(actor.timeZone === undefined ? {} : { timeZone: actor.timeZone }),
+      },
+    } satisfies AdminBatchChunk);
+    return queued.id;
+  };

package/src/batch-matching.ts

@@ -0,0 +1,92 @@
+// "All matching" as ONE set-based call: an action that declares `matching` is handed the list's own
+// `where` and answers `{ affected, remaining }` — the shape of a store's bounded bulk verb. Decided
+// by the batch's gate, confirmed as a set, audited as one entry; `batch.ts` routes here.
+
+import type { AdminDecision } from './authz';
+import type { CrudCtx } from './crud';
+import { type AdminListRequest, listWhere } from './list-scope';
+import { ADMIN_DESTROY, CONFIRMATION_REQUIRED_REASON, confirmationToken } from './permissions';
+import type { AdminAction, AdminActionCtx, AdminMatchingResult } from './registry';
+import type { AdminResource } from './resource';
+
+/** The reason the one entry of a set-based batch carries. */
+export const BATCH_MATCHING_REASON = 'admin.batch.matching';
+const MATCHING_FAILED_REASON = 'admin.error.action-failed';
+
+/** The token a destructive set-based batch is typed against: the count is the store's to know. */
+export const matchingConfirmationToken = (entity: string): string =>
+  confirmationToken(entity, 'all matching');
+
+export type MatchingAnswer =
+  | { readonly ok: true; readonly result: AdminMatchingResult }
+  | { readonly ok: false; readonly token: string; readonly decision: AdminDecision };
+
+export interface MatchingInput {
+  readonly resource: AdminResource;
+  readonly action: AdminAction & Required<Pick<AdminAction, 'matching'>>;
+  readonly ctx: CrudCtx;
+  readonly request: Pick<AdminListRequest, 'scope' | 'filters'>;
+  /** Already validated against the action's schema. */
+  readonly input: Readonly<Record<string, unknown>>;
+  readonly confirmation?: string | undefined;
+  /** The batch's own grant, decided before this is called. */
+  readonly decision: AdminDecision;
+}
+
+export async function runMatching(args: MatchingInput): Promise<MatchingAnswer> {
+  const { resource, action, ctx } = args;
+  // `expected`, as the gate names it: a typed-to-confirm echo the page prints, not a secret.
+  const expected = matchingConfirmationToken(resource.name);
+  if (action.destructive === true && args.confirmation !== expected) {
+    return {
+      ok: false,
+      token: expected,
+      decision: {
+        allowed: false,
+        permission: ADMIN_DESTROY,
+        reason: CONFIRMATION_REQUIRED_REASON,
+        trace: [`confirmation: expected "${expected}"`],
+      },
+    };
+  }
+  // The list's own composition, the row scope first: an org-scoped operator's set is that org's.
+  const { where } = listWhere(resource, ctx.actor, args.request);
+  const actionCtx: AdminActionCtx = {
+    requestId: ctx.requestId,
+    actorId: ctx.actor.id,
+    locale: ctx.actor.locale ?? 'en',
+    timeZone: ctx.actor.timeZone ?? 'UTC',
+  };
+  const entry = {
+    requestId: ctx.requestId,
+    actor: ctx.actor,
+    operation: action.name,
+    kind: 'action',
+    entity: resource.name,
+    entityId: null,
+    permission: args.decision.permission,
+  } as const;
+  let result: AdminMatchingResult;
+  try {
+    result = await action.matching({ where, input: args.input, ctx: actionCtx });
+  } catch (error) {
+    // The gate's rule: the failure is recorded before it travels, and nothing is read off it.
+    await ctx.audit.append({
+      ...entry,
+      outcome: 'failed',
+      reason: MATCHING_FAILED_REASON,
+      diff: [],
+    });
+    throw error;
+  }
+  await ctx.audit.append({
+    ...entry,
+    outcome: 'allowed',
+    reason: BATCH_MATCHING_REASON,
+    diff: [
+      { field: 'affected', before: null, after: result.affected },
+      { field: 'remaining', before: null, after: result.remaining },
+    ],
+  });
+  return { ok: true, result };
+}