@ultimat3/admin 21.0.0 → 22.0.0

package/README.md

@@ -230,3 +230,19 @@ Panes are off until enabled, and `runAiPane` refuses (never no-ops) without a ru
 ## Errors
 
 `X_ADMIN_ENTITY_UNKNOWN` · `X_ADMIN_FIELD_UNSUPPORTED` · `X_ADMIN_POLICY_MISSING` · `X_ADMIN_PAGE_UNGUARDED` · `X_ADMIN_PAGE_PATH_INVALID` · `X_ADMIN_DENIED` · `X_ADMIN_TOOL_FORBIDDEN` · `X_ADMIN_INVALID` · `X_DEV_DASHBOARD_IN_PROD` · `X_NOT_IMPLEMENTED` (an unwired `/_x` source, carrying the wiring line).
+
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `AdminActionDuplicateError` | `X_ADMIN_ACTION_DUPLICATE` | `src/errors.ts` |
+| `AdminEntityUnknownError` | `X_ADMIN_ENTITY_UNKNOWN` | `src/errors.ts` |
+| `AdminFieldUnsupportedError` | `X_ADMIN_FIELD_UNSUPPORTED` | `src/errors.ts` |
+| `AdminPagePathInvalidError` | `X_ADMIN_PAGE_PATH_INVALID` | `src/errors.ts` |
+| `AdminPageUnguardedError` | `X_ADMIN_PAGE_UNGUARDED` | `src/errors.ts` |
+| `AdminPolicyMissingError` | `X_ADMIN_POLICY_MISSING` | `src/errors.ts` |
+| `DevDashboardInProdError` | `X_DEV_DASHBOARD_IN_PROD` | `src/errors.ts` |
+| `DevSourceUnavailableError` | `X_NOT_IMPLEMENTED` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/admin",
-  "version": "21.0.0",
+  "version": "22.0.0",
   "description": "Two dashboards: the /_x framework dev panels and the generated, AI-first app admin",
   "license": "MIT",
   "type": "module",
@@ -32,20 +32,20 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "21.0.0",
-    "@ultimat3/ai": "21.0.0",
-    "@ultimat3/cache": "21.0.0",
-    "@ultimat3/core": "21.0.0",
-    "@ultimat3/db": "21.0.0",
-    "@ultimat3/entity": "21.0.0",
-    "@ultimat3/i18n": "21.0.0",
-    "@ultimat3/jobs": "21.0.0",
-    "@ultimat3/mcp": "21.0.0",
-    "@ultimat3/money": "21.0.0",
-    "@ultimat3/policy": "21.0.0",
-    "@ultimat3/query": "21.0.0",
-    "@ultimat3/render": "21.0.0",
-    "@ultimat3/schema": "21.0.0",
-    "@ultimat3/ui": "21.0.0"
+    "@ultimat3/action": "22.0.0",
+    "@ultimat3/ai": "22.0.0",
+    "@ultimat3/cache": "22.0.0",
+    "@ultimat3/core": "22.0.0",
+    "@ultimat3/db": "22.0.0",
+    "@ultimat3/entity": "22.0.0",
+    "@ultimat3/i18n": "22.0.0",
+    "@ultimat3/jobs": "22.0.0",
+    "@ultimat3/mcp": "22.0.0",
+    "@ultimat3/money": "22.0.0",
+    "@ultimat3/policy": "22.0.0",
+    "@ultimat3/query": "22.0.0",
+    "@ultimat3/render": "22.0.0",
+    "@ultimat3/schema": "22.0.0",
+    "@ultimat3/ui": "22.0.0"
   }
 }

package/src/action-gate.ts

@@ -11,7 +11,12 @@ import {
   type AdminSubject,
   decideAll,
 } from './authz';
-import { ADMIN_DESTROY, ADMIN_WRITE, CONFIRMATION_REQUIRED_REASON } from './permissions';
+import {
+  ADMIN_DESTROY,
+  ADMIN_WRITE,
+  CONFIRMATION_REQUIRED_REASON,
+  confirmationToken,
+} from './permissions';
 import type { AdminAction, AdminActionCtx } from './registry';
 
 export interface AdminActionButton {
@@ -94,9 +99,16 @@ export interface InvokeInput<Input, Output> {
   readonly audit: AuditLog;
   readonly requestId: string;
   readonly subject?: AdminSubject;
-  /** Echo of `confirmationToken(entity, id)`. Required for a destructive action. */
+  /**
+   * 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`
+   * until 22.0.0, and with both omitted `undefined !== undefined` ran the action unconfirmed.
+   *
+   * A type-to-confirm guard against ACCIDENTS, the same design as `adminDestroy`: the token is not
+   * a secret, and a hostile caller can compute it. What stops that caller is the `admin:destroy`
+   * permission this gate checks first.
+   */
   readonly confirmation?: string;
-  readonly expectedConfirmation?: string;
   readonly locale?: string;
   readonly timeZone?: string;
   /** Before/after of the affected row, when the caller knows it. Always logged. */
@@ -134,12 +146,13 @@ export async function invokeAdminAction<Input, Output>(
     };
   }
 
-  if (action.destructive === true && args.confirmation !== args.expectedConfirmation) {
+  const expected = confirmationToken(entity, entityId ?? '');
+  if (action.destructive === true && args.confirmation !== expected) {
     const refused: AdminDecision = {
       allowed: false,
       permission: ADMIN_DESTROY,
       reason: CONFIRMATION_REQUIRED_REASON,
-      trace: [`confirmation: expected "${args.expectedConfirmation ?? ''}"`],
+      trace: [`confirmation: expected "${expected}"`],
     };
     return {
       ok: false,

package/src/crud.ts

@@ -69,6 +69,18 @@ export function decideOperation(
    */
   row?: AdminRow | null,
 ): AdminDecision {
+  // First, before any grant is consulted: an operation the resource does not OFFER is refused for
+  // everyone. `canOperate` checked this for the nav, the buttons and the MCP tools, and the three
+  // direct write functions did not — a `['list', 'detail']` resource deleted a row through
+  // `adminDestroy`. Here, every caller of this function asks it.
+  if (!operationOffered(resource, op)) {
+    return {
+      allowed: false,
+      permission: adminPermissionFor(op),
+      reason: OPERATION_NOT_OFFERED_REASON,
+      trace: [`operations: ${resource.name} does not offer ${op}`],
+    };
+  }
   return decideAll(ctx.authz, permissionsForOperation(resource.name, op), ctx.actor, {
     entity: resource.name,
     ...(id === undefined ? {} : { id }),
@@ -76,9 +88,16 @@ export function decideOperation(
   });
 }
 
+/** Whether the resource declares this operation at all — the one answer, `decideOperation`'s. */
+export const operationOffered = (resource: AdminResource, op: AdminOperation): boolean =>
+  resource.operations.includes(op);
+
+/** The key an operation the resource does not offer is refused with. */
+export const OPERATION_NOT_OFFERED_REASON = 'admin.error.operation-not-offered';
+
 /** `true` when the operation should be offered at all — nav, buttons, MCP tool list. */
 export function canOperate(resource: AdminResource, op: AdminOperation, ctx: CrudCtx): boolean {
-  return resource.operations.includes(op) && decideOperation(resource, op, ctx).allowed;
+  return decideOperation(resource, op, ctx).allowed;
 }
 
 const redactedFields = (resource: AdminResource): readonly string[] =>

package/src/mcp.ts

@@ -35,8 +35,8 @@ import {
 } from './crud';
 import type { AdminFieldType } from './fields';
 import { type AdminMcpTool, adminMcpTools, adminToolCatalog } from './mcp-tools';
-import { confirmationToken } from './permissions';
 import type { AdminAction, AdminRow } from './registry';
+import { repoOf } from './resource';
 import { adminSearch } from './search';
 
 export type McpInput = Readonly<Record<string, unknown>>;
@@ -111,6 +111,13 @@ async function dispatch(
       return { ok: false, error: 'X_ADMIN_TOOL_FORBIDDEN', reason: 'action is not registered' };
     }
     const id = str(input, 'id');
+    // The row a row-level rule decides about, loaded through the resource that OWNS the action —
+    // what the UI's action button does. Without it the subject carried an id and no row, so an
+    // ownership rule could never allow. `null` for a row that does not exist: no evidence of
+    // permission, same contract as an action's `row:` loader. A global action names no resource.
+    const owner = app.resources.find((resource) => resource.actions.includes(action));
+    const row =
+      owner === undefined || id === '' ? undefined : ((await repoOf(owner).find(id)) ?? null);
     const result = await invokeAdminAction({
       action,
       input: withoutKeys(input, ['confirmation']),
@@ -121,10 +128,11 @@ async function dispatch(
       subject: {
         ...(action.entity === undefined ? {} : { entity: action.entity }),
         ...(id === '' ? {} : { id }),
+        ...(row === undefined ? {} : { row }),
       },
+      // The agent must echo the token, exactly as the UI makes an operator type it — and the gate
+      // derives the token it expects from the entity and `subject.id` above.
       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 }