@ultimat3/admin 1.0.0

package/src/mcp.ts

@@ -0,0 +1,304 @@
+// The AI-first surface: the admin's resources and actions as MCP tools, wired through
+// `defineAppMcp` so the user's agents drive the user's app. Same authz, same audit, same
+// confirmation rules as the buttons — this file adds a transport, not a second back door.
+
+import { agentActor } from '@ultimat3/core';
+import {
+  type AnyMcpTool,
+  type AppMcp,
+  defineAppMcp,
+  type JsonSchema,
+  jsonResult,
+  type McpCaller,
+  type McpToolResult,
+  type ResolvedToken,
+  type ToolArgs,
+} from '@ultimat3/mcp';
+import { invokeAdminAction } from './action-gate';
+import type { AdminApp } from './admin';
+import type { AdminActor } from './authz';
+import {
+  adminCreate,
+  adminDestroy,
+  adminDetail,
+  adminList,
+  adminUpdate,
+  type CrudCtx,
+  type CrudResult,
+} from './crud';
+import type { AdminFieldType } from './fields';
+import {
+  type AdminMcpTool,
+  type AdminToolField,
+  adminMcpTools,
+  adminToolCatalog,
+} from './mcp-tools';
+import { confirmationToken } from './permissions';
+import type { AdminAction, AdminRow } from './registry';
+import { adminSearch } from './search';
+
+export type McpInput = Readonly<Record<string, unknown>>;
+
+export type AdminToolResult =
+  | { readonly ok: true; readonly data: unknown }
+  | { readonly ok: false; readonly error: string; readonly reason: string };
+
+const str = (input: McpInput, key: string): string => {
+  const value = input[key];
+  return typeof value === 'string' ? value : '';
+};
+
+const num = (input: McpInput, key: string): number | undefined => {
+  const value = input[key];
+  return typeof value === 'number' ? value : undefined;
+};
+
+const withoutKeys = (input: McpInput, keys: readonly string[]): Record<string, unknown> => {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (!keys.includes(key)) out[key] = value;
+  }
+  return out;
+};
+
+const actionByName = (app: AdminApp, name: string): AdminAction | undefined =>
+  [...app.resources.flatMap((resource) => resource.actions), ...app.globalActions].find(
+    (action) => action.name === name,
+  );
+
+/**
+ * Dispatch one tool call. The tool must be in this actor's allowed list — resolving the name
+ * against `adminMcpTools()` is what makes "the agent sees what it may do" true rather than
+ * aspirational.
+ */
+export async function callAdminTool(
+  app: AdminApp,
+  ctx: CrudCtx,
+  name: string,
+  input: McpInput,
+): Promise<AdminToolResult> {
+  const tool = adminMcpTools(app, ctx).find((candidate) => candidate.name === name);
+  // NOT dead code, and not the only gate: the registry's `visibleTo` predicate already hides
+  // this tool from a caller who may not use it, so an MCP call cannot reach here refused.
+  // Every other entry point (a direct `callAdminTool`, a future transport) can, so this stays
+  // as defence in depth — the authz decision must not live only in the catalog filter.
+  if (tool === undefined) {
+    return {
+      ok: false,
+      error: 'X_ADMIN_TOOL_FORBIDDEN',
+      reason: `tool "${name}" is not available to actor ${ctx.actor.id}`,
+    };
+  }
+  return dispatch(app, ctx, tool, input);
+}
+
+async function dispatch(
+  app: AdminApp,
+  ctx: CrudCtx,
+  tool: AdminMcpTool,
+  input: McpInput,
+): Promise<AdminToolResult> {
+  if (tool.kind === 'search') {
+    const result = await adminSearch({ term: str(input, 'term'), resources: app.resources, ctx });
+    return { ok: true, data: result };
+  }
+
+  if (tool.kind === 'action') {
+    const action = actionByName(app, tool.action ?? '');
+    if (action === undefined) {
+      return { ok: false, error: 'X_ADMIN_TOOL_FORBIDDEN', reason: 'action is not registered' };
+    }
+    const id = str(input, 'id');
+    const result = await invokeAdminAction({
+      action,
+      input: withoutKeys(input, ['confirmation']),
+      actor: ctx.actor,
+      authz: ctx.authz,
+      audit: ctx.audit,
+      requestId: ctx.requestId,
+      subject: {
+        ...(action.entity === undefined ? {} : { entity: action.entity }),
+        ...(id === '' ? {} : { id }),
+      },
+      confirmation: str(input, 'confirmation'),
+      // The agent must echo the token, exactly as the UI makes an operator type it.
+      expectedConfirmation: confirmationToken(action.entity ?? 'admin', id),
+    });
+    return result.ok
+      ? { ok: true, data: result.value }
+      : { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
+  }
+
+  const resource = app.resource(tool.entity ?? '');
+  switch (tool.kind) {
+    case 'list': {
+      const limit = num(input, 'limit');
+      const result = await adminList(resource, ctx, {
+        cursor: str(input, 'cursor'),
+        ...(limit === undefined ? {} : { limit }),
+      });
+      return result.ok
+        ? { ok: true, data: result.page }
+        : { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
+    }
+    case 'read':
+      return crudResult(await adminDetail(resource, ctx, str(input, 'id')));
+    case 'create':
+      return crudResult(await adminCreate(resource, ctx, input));
+    case 'update':
+      return crudResult(
+        await adminUpdate(resource, ctx, str(input, 'id'), withoutKeys(input, ['id'])),
+      );
+    case 'delete':
+      return crudResult(
+        await adminDestroy(resource, ctx, str(input, 'id'), str(input, 'confirmation')),
+      );
+  }
+}
+
+function crudResult(result: CrudResult<AdminRow>): AdminToolResult {
+  if (result.ok) return { ok: true, data: result.row };
+  return result.kind === 'denied'
+    ? { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason }
+    : { ok: false, error: 'X_ADMIN_INVALID', reason: JSON.stringify(result.issues) };
+}
+
+export interface AdminMcpOptions {
+  readonly app: AdminApp;
+  /** Resolve the MCP session's actor. The same hook the HTTP surface uses, never a bypass. */
+  actor(session: { readonly token?: string }): Promise<AdminActor | null> | AdminActor | null;
+  readonly requestId?: () => string;
+}
+
+/** A field type an agent can actually send. Anything richer is a JSON object on the wire. */
+const JSON_TYPE: Readonly<Record<AdminFieldType, NonNullable<JsonSchema['type']>>> = {
+  text: 'string',
+  textarea: 'string',
+  number: 'number',
+  money: 'object',
+  boolean: 'boolean',
+  enum: 'string',
+  date: 'string',
+  timestamptz: 'string',
+  timezone: 'string',
+  locale: 'string',
+  json: 'object',
+  relation: 'string',
+  file: 'string',
+};
+
+const inputSchema = (fields: readonly AdminToolField[]): JsonSchema => ({
+  type: 'object',
+  properties: Object.fromEntries(
+    fields.map((field) => [field.name, { type: JSON_TYPE[field.type] }]),
+  ),
+  required: fields.filter((field) => field.required).map((field) => field.name),
+  additionalProperties: false,
+});
+
+/**
+ * `caller.actor` is whatever `resolveToken` returned, so the identity the tool runs as is the
+ * one the session authenticated as — id and roles are all authz reads.
+ */
+const adminActorOf = (caller: McpCaller): AdminActor => ({
+  id: caller.actor.id,
+  roles: caller.actor.roles,
+});
+
+/**
+ * The tool names one caller may call, memoized.
+ *
+ * WHY memoize: visibility is asked once per tool and each answer re-derives the whole
+ * catalog, so an unmemoized `tools/list` costs O(tools²) authz decisions.
+ *
+ * WHY a `WeakMap` keyed on the caller OBJECT: an entry can never hand one caller another's
+ * answer, and it is collected with the caller, so there is nothing to evict.
+ *
+ * Its LIFETIME is therefore the transport's, and the two transports differ:
+ *
+ * | Transport | `McpCaller` built | Cache grain |
+ * |---|---|---|
+ * | HTTP (`transport-http.ts`) | inside `route.handle`, per request | per request |
+ * | stdio (`transport-stdio.ts`) | once, in `StdioTransportInput` | per connection |
+ *
+ * So over stdio a permission change made mid-connection is NOT observed until the client
+ * reconnects. That is accepted, not overlooked: the stdio peer is the local developer's own
+ * shell, which launched this process and already holds that developer's authority, and the
+ * session is short and re-launched per editor/agent run. A connection-scoped catalog is the
+ * intended grain there — an invalidation hook would add a second source of truth for
+ * visibility to keep in sync with `adminMcpTools`, which is the drift this file avoids
+ * everywhere else. Over HTTP, where a token can outlive a permission change, the grain is
+ * already per request and the question does not arise.
+ *
+ * WHY keyed by app too: one process can mount two admins, and their catalogs differ.
+ */
+const allowedByCaller = new WeakMap<McpCaller, Map<AdminApp, ReadonlySet<string>>>();
+
+function allowedToolNames(
+  opts: AdminMcpOptions,
+  requestId: () => string,
+  caller: McpCaller,
+): ReadonlySet<string> {
+  const perApp = allowedByCaller.get(caller) ?? new Map<AdminApp, ReadonlySet<string>>();
+  const cached = perApp.get(opts.app);
+  if (cached !== undefined) return cached;
+
+  const ctx = opts.app.ctx({ actor: adminActorOf(caller), requestId: requestId() });
+  // `adminMcpTools` is the actor's allowed list — the same derivation the UI's buttons use.
+  // Never a second decision written for MCP.
+  const names: ReadonlySet<string> = new Set(adminMcpTools(opts.app, ctx).map(({ name }) => name));
+  perApp.set(opts.app, names);
+  allowedByCaller.set(caller, perApp);
+  return names;
+}
+
+function toMcpTool(opts: AdminMcpOptions, requestId: () => string, tool: AdminMcpTool): AnyMcpTool {
+  return {
+    name: tool.name,
+    description: tool.description,
+    inputSchema: inputSchema(tool.input),
+    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
+    // and turn the catalog into something an agent can enumerate by probing names. The
+    // predicate never sees call arguments, so visibility stays input-independent.
+    visibleTo: (caller: McpCaller): boolean =>
+      allowedToolNames(opts, requestId, caller).has(tool.name),
+    async handle(args: ToolArgs, caller: McpCaller): Promise<McpToolResult> {
+      const ctx = opts.app.ctx({ actor: adminActorOf(caller), requestId: requestId() });
+      const result = await callAdminTool(opts.app, ctx, tool.name, args);
+      if (result.ok) return jsonResult(result.data);
+      // An expected outcome the model should reason about (a policy said no), not a
+      // protocol error: the transport still answers 200 with the denial in the body.
+      return { ...jsonResult({ error: result.error, reason: result.reason }), isError: true };
+    },
+  };
+}
+
+/**
+ * Mount the admin as an app MCP server.
+ *
+ * The catalog is built once but answered per caller: every tool carries a `visibleTo`
+ * predicate that re-derives that actor's allowed tools, so `tools/list` is answered per
+ * caller — one `McpCaller` per HTTP request, one per stdio connection — and a tool the actor
+ * may not use is ABSENT from it, while a direct call answers ToolNotFound, never Forbidden.
+ * Forbidden would confirm the tool exists, leaking every entity name and operation to anyone
+ * who probes. Every call still goes through `callAdminTool`, which re-checks the same allowed
+ * list on dispatch, exactly as the UI refuses a button the actor may not click.
+ */
+export function adminMcp(opts: AdminMcpOptions): AppMcp {
+  const requestId = opts.requestId ?? ((): string => crypto.randomUUID());
+
+  return defineAppMcp({
+    name: 'admin',
+    tools: adminToolCatalog(opts.app).map((tool) => toMcpTool(opts, requestId, tool)),
+    async resolveToken(token: string): Promise<ResolvedToken | null> {
+      const actor = await opts.actor({ token });
+      // `kind: 'agent'` — the same actor shape an agent gets everywhere else, so a policy
+      // that distinguishes agents from people keeps working on this surface.
+      return actor === null
+        ? null
+        : { actor: agentActor({ id: actor.id, roles: actor.roles ?? [] }), scopes: new Set() };
+    },
+  });
+}

package/src/nav.ts

@@ -0,0 +1,97 @@
+// Navigation derived from the resources, grouped, and filtered by the same `admin:read` +
+// `<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 type { CrudCtx } from './crud';
+import { canOperate } from './crud';
+import type { AdminResource } from './resource';
+
+export interface NavItem {
+  readonly key: string;
+  readonly labelKey: string;
+  readonly href: string;
+  /** The entity this item lists, or `null` for a built-in page. */
+  readonly entity: string | null;
+}
+
+export interface NavGroup {
+  readonly key: string;
+  readonly labelKey: string;
+  readonly items: readonly NavItem[];
+}
+
+export interface NavOptions {
+  /** Explicit group order and membership: `{ 'admin.group.content': ['post', 'tag'] }`. */
+  readonly groups?: Readonly<Record<string, readonly string[]>>;
+  /** Extra items (dashboards, links) appended to their group. */
+  readonly extra?: readonly (NavItem & { readonly group: string })[];
+}
+
+const itemFor = (resource: AdminResource): NavItem => ({
+  key: resource.name,
+  labelKey: resource.titleKey,
+  href: resource.path,
+  entity: resource.name,
+});
+
+/**
+ * Declaration order is the default order: an entity registry is written in the order the
+ * domain reads, and re-sorting it alphabetically loses that.
+ */
+export function adminNav(
+  resources: readonly AdminResource[],
+  opts: NavOptions = {},
+): readonly NavGroup[] {
+  const byKey = new Map<string, NavItem[]>();
+  const order: string[] = [];
+
+  const push = (groupKey: string, item: NavItem): void => {
+    let bucket = byKey.get(groupKey);
+    if (bucket === undefined) {
+      bucket = [];
+      byKey.set(groupKey, bucket);
+      order.push(groupKey);
+    }
+    bucket.push(item);
+  };
+
+  if (opts.groups !== undefined) {
+    for (const [groupKey, names] of Object.entries(opts.groups)) {
+      for (const name of names) {
+        const resource = resources.find((candidate) => candidate.name === name);
+        if (resource !== undefined) push(groupKey, itemFor(resource));
+      }
+    }
+  }
+
+  const placed = new Set([...byKey.values()].flat().map((item) => item.entity ?? item.key));
+  for (const resource of resources) {
+    if (placed.has(resource.name)) continue;
+    push(resource.group, itemFor(resource));
+  }
+
+  for (const item of opts.extra ?? []) push(item.group, item);
+
+  return order.map((groupKey) => ({
+    key: groupKey,
+    labelKey: groupKey,
+    items: byKey.get(groupKey) ?? [],
+  }));
+}
+
+/** Drop items the actor cannot list, then drop groups that emptied out. */
+export function visibleNav(
+  nav: readonly NavGroup[],
+  resources: readonly AdminResource[],
+  ctx: CrudCtx,
+): readonly NavGroup[] {
+  const visible = (item: NavItem): boolean => {
+    if (item.entity === null) return true;
+    const resource = resources.find((candidate) => candidate.name === item.entity);
+    return resource !== undefined && canOperate(resource, 'list', ctx);
+  };
+
+  return nav
+    .map((group) => ({ ...group, items: group.items.filter(visible) }))
+    .filter((group) => group.items.length > 0);
+}

package/src/pagination.ts

@@ -0,0 +1,152 @@
+// Cursor pagination, and only cursor pagination. `AdminListQuery` has no `offset` field, so
+// "page 400" cannot be expressed: an operator paging a table that is being written to would
+// otherwise skip and repeat rows, and every page would re-scan everything before it.
+// The position itself is encoded by `@ultimat3/core` — one signed cursor format, framework-wide.
+
+import { decodeCursor, encodeCursor, isUltimateError } from '@ultimat3/core';
+import type { AdminFilter, AdminListQuery, AdminRow, AdminSort } from './registry';
+import { rowId } from './registry';
+import { type AdminResource, repoOf } from './resource';
+
+export interface AdminCursor {
+  readonly field: string;
+  readonly value: string;
+  readonly id: string;
+  readonly direction: 'after' | 'before';
+}
+
+/** Asking for the name alone keeps the codec free of the row generic. */
+type CursorResource = Pick<AdminResource, 'name'>;
+
+/**
+ * The signed scope binds a cursor to the resource that issued it: a position taken from the
+ * posts table cannot be replayed against users, whatever an operator pastes into the URL.
+ */
+const cursorScope = (resource: CursorResource): string => `admin:${resource.name}`;
+
+export function encodeAdminCursor(resource: CursorResource, cursor: AdminCursor): string {
+  return encodeCursor({
+    scope: cursorScope(resource),
+    key: [cursor.direction, cursor.field, cursor.value],
+    id: cursor.id,
+  });
+}
+
+/**
+ * An unreadable cursor yields `null`, i.e. the first page — a stale bookmark or a hand-edited
+ * URL should show the operator page one, not an error page. Deliberately softer than the repo
+ * and the read primitive, which surface `X_CURSOR_INVALID`: those are called by code that must
+ * learn it paged wrong, while a human just wants the table to render. Forgery is covered either
+ * way — core verifies the signature before the payload is trusted, so a tampered or borrowed
+ * cursor lands on page one instead of a seek position the client invented.
+ */
+export function decodeAdminCursor(
+  resource: CursorResource,
+  raw: string | null | undefined,
+): AdminCursor | null {
+  if (raw === null || raw === undefined || raw === '') return null;
+  try {
+    const payload = decodeCursor(raw, cursorScope(resource));
+    if (payload.key.length !== 3) return null;
+    const [direction, field, value] = payload.key;
+    if (direction !== 'after' && direction !== 'before') return null;
+    if (typeof field !== 'string' || typeof value !== 'string') return null;
+    return { direction, field, value, id: payload.id };
+  } catch (error) {
+    if (isUltimateError(error) && error.code === 'X_CURSOR_INVALID') return null;
+    throw error;
+  }
+}
+
+export interface PageRequest {
+  readonly cursor?: string | null;
+  readonly limit?: number;
+  readonly sort?: AdminSort;
+  readonly where?: readonly AdminFilter[];
+}
+
+export interface AdminPage<Row extends AdminRow> {
+  readonly rows: readonly Row[];
+  readonly sort: AdminSort;
+  readonly pageSize: number;
+  readonly nextCursor: string | null;
+  readonly prevCursor: string | null;
+  readonly hasMore: boolean;
+}
+
+/** The repo query for one page. Asks for `limit + 1` to learn whether a next page exists. */
+export function listQuery<Row extends AdminRow>(
+  resource: AdminResource<Row>,
+  req: PageRequest = {},
+): AdminListQuery {
+  const sort = req.sort ?? resource.defaultSort;
+  const limit = Math.max(1, Math.min(req.limit ?? resource.pageSize, 200));
+  const cursor = decodeAdminCursor(resource, req.cursor);
+  const bound =
+    cursor === null ? undefined : { field: cursor.field, value: cursor.value, id: cursor.id };
+
+  return {
+    sort,
+    limit: limit + 1,
+    ...(req.where === undefined ? {} : { where: req.where }),
+    ...(bound === undefined
+      ? {}
+      : cursor?.direction === 'before'
+        ? { before: bound }
+        : { after: bound }),
+  };
+}
+
+const cursorValue = (row: AdminRow, field: string): string => {
+  const value = row[field];
+  if (value instanceof Date) return value.toISOString();
+  return value === null || value === undefined ? '' : String(value);
+};
+
+/** Turn `limit + 1` rows into a page plus the cursors that walk off either end. */
+export function pageFrom<Row extends AdminRow>(
+  resource: AdminResource<Row>,
+  req: PageRequest,
+  fetched: readonly Row[],
+): 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 last = rows[rows.length - 1];
+  const first = rows[0];
+  const incoming = decodeAdminCursor(resource, req.cursor);
+
+  return {
+    rows,
+    sort,
+    pageSize,
+    hasMore,
+    nextCursor:
+      hasMore && last !== undefined
+        ? encodeAdminCursor(resource, {
+            direction: 'after',
+            field: sort.field,
+            value: cursorValue(last, sort.field),
+            id: rowId(last, resource.idField),
+          })
+        : null,
+    prevCursor:
+      incoming !== null && first !== undefined
+        ? encodeAdminCursor(resource, {
+            direction: 'before',
+            field: sort.field,
+            value: cursorValue(first, sort.field),
+            id: rowId(first, resource.idField),
+          })
+        : null,
+  };
+}
+
+export async function fetchPage<Row extends AdminRow>(
+  resource: AdminResource<Row>,
+  req: PageRequest = {},
+): Promise<AdminPage<Row>> {
+  const fetched = await repoOf(resource).list(listQuery(resource, req));
+  return pageFrom(resource, req, fetched);
+}

package/src/permissions.ts

@@ -0,0 +1,92 @@
+// The admin's own permission set, and the two rules that hang off it: destructive
+// operations always re-confirm, and destructive operations are always audited. Both are
+// data here (not a code path in a view) so the UI, the HTTP call, and the MCP tool read the
+// same table instead of each remembering the rule.
+
+export const ADMIN_READ = 'admin:read';
+export const ADMIN_WRITE = 'admin:write';
+export const ADMIN_DESTROY = 'admin:destroy';
+export const ADMIN_IMPERSONATE = 'admin:impersonate';
+
+export const ADMIN_PERMISSIONS = [
+  ADMIN_READ,
+  ADMIN_WRITE,
+  ADMIN_DESTROY,
+  ADMIN_IMPERSONATE,
+] as const;
+
+export type AdminPermission = (typeof ADMIN_PERMISSIONS)[number];
+
+/** Every mutation or read the admin can perform on a resource. */
+export type AdminOperation = 'list' | 'detail' | 'search' | 'create' | 'update' | 'delete';
+
+export const ADMIN_OPERATIONS = ['list', 'detail', 'search', 'create', 'update', 'delete'] as const;
+
+export interface AdminPermissionRule {
+  /** The admin-level gate. An actor also needs the per-entity permission. */
+  readonly permission: AdminPermission;
+  /** Destructive: the client must echo a confirmation token before the call runs. */
+  readonly destructive: boolean;
+  /** Never false. Present so the field exists in `--json` output and in tests. */
+  readonly audited: true;
+  readonly labelKey: string;
+}
+
+const rule = (
+  permission: AdminPermission,
+  destructive: boolean,
+  op: AdminOperation,
+): AdminPermissionRule => ({
+  permission,
+  destructive,
+  audited: true,
+  labelKey: `admin.operation.${op}`,
+});
+
+export const ADMIN_OPERATION_RULES: Readonly<Record<AdminOperation, AdminPermissionRule>> = {
+  list: rule(ADMIN_READ, false, 'list'),
+  detail: rule(ADMIN_READ, false, 'detail'),
+  search: rule(ADMIN_READ, false, 'search'),
+  create: rule(ADMIN_WRITE, false, 'create'),
+  update: rule(ADMIN_WRITE, false, 'update'),
+  delete: rule(ADMIN_DESTROY, true, 'delete'),
+};
+
+export function ruleFor(op: AdminOperation): AdminPermissionRule {
+  return ADMIN_OPERATION_RULES[op];
+}
+
+/** The admin-level permission an operation needs, before the per-entity one. */
+export function adminPermissionFor(op: AdminOperation): AdminPermission {
+  return ADMIN_OPERATION_RULES[op].permission;
+}
+
+/** The per-entity permission, so `post:delete` and `admin:destroy` must BOTH hold. */
+export function entityPermissionFor(entity: string, op: AdminOperation): string {
+  const verb = op === 'delete' ? 'delete' : op === 'create' || op === 'update' ? 'write' : 'read';
+  return `${entity}:${verb}`;
+}
+
+export function isDestructive(op: AdminOperation): boolean {
+  return ADMIN_OPERATION_RULES[op].destructive;
+}
+
+/**
+ * The token a destructive call must echo. Deliberately the human-readable record id: a
+ * typed-out id is a re-read of what is about to be deleted, and an agent cannot guess it.
+ */
+export function confirmationToken(entity: string, id: string): string {
+  return `${entity}:${id}`;
+}
+
+export const CONFIRMATION_REQUIRED_REASON = 'admin.error.confirmation-required';
+
+/** The spec `definePermissions()` is fed with. Kept pure so tests need no policy runtime. */
+export const ADMIN_PERMISSION_SPEC: Readonly<
+  Record<AdminPermission, { readonly descriptionKey: string; readonly implies: readonly string[] }>
+> = {
+  [ADMIN_READ]: { descriptionKey: 'admin.permission.read', implies: [] },
+  [ADMIN_WRITE]: { descriptionKey: 'admin.permission.write', implies: [ADMIN_READ] },
+  [ADMIN_DESTROY]: { descriptionKey: 'admin.permission.destroy', implies: [ADMIN_WRITE] },
+  [ADMIN_IMPERSONATE]: { descriptionKey: 'admin.permission.impersonate', implies: [ADMIN_READ] },
+};