@ultimat3/admin 27.1.0 → 27.2.1

package/README.md

@@ -86,7 +86,7 @@ closed `<details>` whose summary reads "N of M allowed".
 | `audit` | `postgresAuditLog()` (the table `x_admin_audit`) or `memoryAuditLog({ sinks })` | a memory ring |
 
 Three authz constructors, one interface: `roleAuthz()` (the default), `policyAuthz({ policies })`
-when a rule reads the row or the tenant, `singlePolicyAuthz(policy)` when one grant runs the whole
+when a rule reads the row or the tenant (a permission the map omits falls back to the role map), `singlePolicyAuthz(policy)` when one grant runs the whole
 admin.
 
 ### No script

package/package.json

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

package/src/actor.ts

@@ -21,6 +21,7 @@ export const adminActorFrom = (
     : {
         id: actor.id,
         roles: actor.roles,
+        ...(actor.permissions.length === 0 ? {} : { permissions: actor.permissions }),
         locale,
         timeZone,
         ...(actor.orgId === undefined ? {} : { orgId: actor.orgId }),

package/src/authz.ts

@@ -20,6 +20,12 @@ export interface AdminActor {
    */
   readonly orgId?: string;
   readonly roles?: readonly string[];
+  /**
+   * Direct grants — `Actor.permissions`, held with or without a role (a break-glass account, a
+   * staff session not yet enrolled in MFA). The request pipeline decides on roles AND these; the
+   * admin read roles only, so a route the pipeline opened answered a 403 screen.
+   */
+  readonly permissions?: readonly string[];
   /** BCP-47. Drives every `t()` call and every `Intl` format in the admin. */
   readonly locale?: string;
   /** IANA zone. The admin refuses to render a timestamp without one. */

package/src/batch-job.ts

@@ -39,6 +39,7 @@ const chunkInput = t.object({
   actor: t.object({
     id: t.string,
     roles: t.array(t.string),
+    permissions: t.optional(t.array(t.string)),
     orgId: t.optional(t.string),
     locale: t.optional(t.string),
     timeZone: t.optional(t.string),
@@ -58,6 +59,8 @@ export interface AdminBatchChunk {
   readonly actor: {
     readonly id: string;
     readonly roles: readonly string[];
+    /** Direct grants: an operator who holds the permission with no role runs the batch too. */
+    readonly permissions?: readonly string[] | undefined;
     readonly orgId?: string | undefined;
     readonly locale?: string | undefined;
     readonly timeZone?: string | undefined;
@@ -87,6 +90,7 @@ export async function runBatchChunk(chunk: AdminBatchChunk): Promise<readonly Ba
   const actor: AdminActor = {
     id: chunk.actor.id,
     roles: chunk.actor.roles,
+    ...(chunk.actor.permissions === undefined ? {} : { permissions: chunk.actor.permissions }),
     ...(chunk.actor.orgId === undefined ? {} : { orgId: chunk.actor.orgId }),
     ...(chunk.actor.locale === undefined ? {} : { locale: chunk.actor.locale }),
     ...(chunk.actor.timeZone === undefined ? {} : { timeZone: chunk.actor.timeZone }),
@@ -99,6 +103,7 @@ export async function runBatchChunk(chunk: AdminBatchChunk): Promise<readonly Ba
       actor: userActor({
         id: actor.id,
         roles: [...(actor.roles ?? [])],
+        permissions: [...(actor.permissions ?? [])],
         ...(actor.orgId === undefined ? {} : { orgId: actor.orgId }),
       }),
     },
@@ -143,6 +148,7 @@ export const batchEnqueue =
       actor: {
         id: actor.id,
         roles: [...(actor.roles ?? [])],
+        ...(actor.permissions === undefined ? {} : { permissions: [...actor.permissions] }),
         ...(actor.orgId === undefined ? {} : { orgId: actor.orgId }),
         ...(actor.locale === undefined ? {} : { locale: actor.locale }),
         ...(actor.timeZone === undefined ? {} : { timeZone: actor.timeZone }),

package/src/mcp.ts

@@ -311,6 +311,8 @@ const inputSchema = (tool: AdminMcpTool): JsonSchema => ({
 const adminActorOf = (caller: McpCaller): AdminActor => ({
   id: caller.actor.id,
   roles: caller.actor.roles,
+  // Direct grants too: the pipeline decides on roles and `permissions` as one set.
+  ...(caller.actor.permissions.length === 0 ? {} : { permissions: caller.actor.permissions }),
   ...(caller.actor.orgId === undefined ? {} : { orgId: caller.actor.orgId }),
 });
 
@@ -453,7 +455,12 @@ export function adminMcp(opts: AdminMcpOptions): AppMcp {
       return actor === null
         ? null
         : {
-            actor: agentActor({ id: actor.id, roles: actor.roles ?? [], orgId: actor.orgId }),
+            actor: agentActor({
+              id: actor.id,
+              roles: actor.roles ?? [],
+              permissions: actor.permissions ?? [],
+              orgId: actor.orgId,
+            }),
             scopes: adminTokenScopes(actor.tokenScopes),
           };
     },

package/src/policy-bridge.ts

@@ -15,6 +15,7 @@ import {
 import {
   type AdminActor,
   type AdminAuthz,
+  type AdminAuthzQuery,
   type AdminDecision,
   type AdminSubject,
   adminAllowed,
@@ -31,7 +32,29 @@ const policyActor = (actor: AdminActor): Actor =>
   // `orgId` rides along, and its absence used to be silent: every admin decision was evaluated
   // with `actor.orgId === undefined`, so an org-scoped rule could not fire and a role-only rule
   // allowed a row from another tenant.
-  userActor({ id: actor.id, roles: actor.roles ?? [], orgId: actor.orgId });
+  // And the direct grants: `can()` reads roles and `permissions` as one set, exactly as the request
+  // pipeline does, so a permission held with no role opens the screen it opens the route for.
+  userActor({
+    id: actor.id,
+    roles: actor.roles ?? [],
+    permissions: actor.permissions ?? [],
+    orgId: actor.orgId,
+  });
+
+/**
+ * One evaluated clause as the line `/_x` prints: `  can(job:read): allow`, indented by depth, its
+ * reason after a refusal. A `TraceEntry` through `String()` read `[object Object]`.
+ */
+function traceLine(entry: unknown): string {
+  if (typeof entry !== 'object' || entry === null) return String(entry);
+  const { label, depth, allowed, reason } = entry as Partial<
+    Record<'label' | 'depth' | 'allowed' | 'reason', unknown>
+  >;
+  const indent = '  '.repeat(typeof depth === 'number' && depth > 0 ? depth : 0);
+  const verdict = allowed === true ? 'allow' : 'deny';
+  const why = typeof reason === 'string' && reason !== '' ? ` (${reason})` : '';
+  return `${indent}${String(label)}: ${verdict}${why}`;
+}
 
 /**
  * `evaluate()`'s result is read structurally: the policy layer owns its own decision type,
@@ -51,12 +74,15 @@ function readDecision(permission: string, result: unknown): AdminDecision {
   };
   const verdict = result === true || bag.allowed === true;
   const reason = typeof inner.reason === 'string' ? inner.reason : 'admin.policy.evaluated';
-  const trace = Array.isArray(bag.trace) ? bag.trace.map((line) => String(line)) : [];
+  const trace = Array.isArray(bag.trace) ? bag.trace.map(traceLine) : [];
   return verdict ? adminAllowed(permission, reason, trace) : adminDenied(permission, reason, trace);
 }
 
-/** `resource:verb` — the only shape `can()` takes. Anything else is denied, never thrown. */
-const isPermission = (value: string): value is Permission => /^[^:]+:[^:]+$/.test(value);
+/**
+ * `resource:verb`, the resource itself colon-scoped or not (`admin:support:write`) — the shape
+ * `Permission` types and `can()` takes. Anything else is denied, never thrown.
+ */
+const isPermission = (value: string): value is Permission => /^[^:]+(?::[^:]+)+$/.test(value);
 
 /**
  * Declare the admin's OWN permissions (`ADMIN_PERMISSIONS`) and the ones a mount DERIVES —
@@ -99,34 +125,34 @@ const evaluated = (
  * whose rules read the row or the tenant passes `policyAuthz({ policies })` instead.
  */
 export function roleAuthz(): AdminAuthz {
-  return {
-    decide({ permission, actor, subject }): AdminDecision {
-      // Asked BEFORE `can()`, which throws on a name the registry lacks: a decision is an answer,
-      // and an undeclared permission is a refusal with its fix, never a 500 out of a nav render.
-      if (!isPermission(permission) || !isKnownPermission(permission)) {
-        return adminDenied(permission, 'admin.policy.missing', [
-          `"${permission}" is not a declared resource:verb permission`,
-          `fix: definePermissions(['${permission}']), then grant it to a role in defineRoles()`,
-        ]);
-      }
-      // `can()` asserts the name against the registry `declareAdminPermissions` filled. The cast
-      // is the same one a route guard's bare string takes: the registry, not the type, is the check.
-      const own = evaluated(permission, can(permission as KnownPermission), actor, subject);
-      if (own.allowed) return own;
-      // The admin's implications, as `staticAuthz` applies them: a role granting `admin:destroy`
-      // holds `admin:write` and `admin:read` too. Without this the same grants answered two ways.
-      for (const implier of impliersOf(permission)) {
-        const carried = evaluated(implier, can(implier as KnownPermission), actor, subject);
-        if (carried.allowed) {
-          return adminAllowed(permission, carried.reason, [
-            ...carried.trace,
-            `${permission} is implied by ${implier}`,
-          ]);
-        }
-      }
-      return own;
-    },
-  };
+  return { decide: decideByRoleMap };
+}
+
+function decideByRoleMap({ permission, actor, subject }: AdminAuthzQuery): AdminDecision {
+  // Asked BEFORE `can()`, which throws on a name the registry lacks: a decision is an answer,
+  // and an undeclared permission is a refusal with its fix, never a 500 out of a nav render.
+  if (!isPermission(permission) || !isKnownPermission(permission)) {
+    return adminDenied(permission, 'admin.policy.missing', [
+      `"${permission}" is not a declared resource:verb permission`,
+      `fix: definePermissions(['${permission}']), then grant it to a role in defineRoles()`,
+    ]);
+  }
+  // `can()` asserts the name against the registry `declareAdminPermissions` filled. The cast
+  // is the same one a route guard's bare string takes: the registry, not the type, is the check.
+  const own = evaluated(permission, can(permission as KnownPermission), actor, subject);
+  if (own.allowed) return own;
+  // The admin's implications, as `staticAuthz` applies them: a role granting `admin:destroy`
+  // holds `admin:write` and `admin:read` too. Without this the same grants answered two ways.
+  for (const implier of impliersOf(permission)) {
+    const carried = evaluated(implier, can(implier as KnownPermission), actor, subject);
+    if (carried.allowed) {
+      return adminAllowed(permission, carried.reason, [
+        ...carried.trace,
+        `${permission} is implied by ${implier}`,
+      ]);
+    }
+  }
+  return own;
 }
 
 /**
@@ -149,20 +175,28 @@ export interface PolicyAuthzInput {
 }
 
 /**
- * Closed by default: a permission with no registered policy is denied, with the fix in the
- * trace. An admin that fails open is worse than an admin that fails visibly.
+ * The map REFINES, the role map GRANTS. A permission with a policy here is decided by it (a row
+ * or tenant rule, or a `deny` that closes what a role grants); one the map omits is decided by
+ * the role map and the actor's direct grants, exactly as `roleAuthz` and the request pipeline
+ * decide it. Still closed: a permission nobody declared is denied with the fix in the trace, and
+ * a declared one is denied by `can()` when neither a role nor the actor's direct grants hold it.
+ *
+ * Until 27.2.0 an omitted permission was denied outright, so the framework's own screens needed
+ * the same grant twice — `job:read` in `defineRoles` AND `'job:read': can('job:read')` here — and
+ * an app that wrote only the first had a jobs dashboard every operator was refused.
  */
 export function policyAuthz(input: PolicyAuthzInput): AdminAuthz {
   return {
-    decide({ permission, actor, subject }): AdminDecision {
-      const policy = input.policies[permission];
-      if (policy === undefined) {
-        return adminDenied(permission, 'admin.policy.missing', [
-          `no policy registered for "${permission}"`,
-          `fix: definePermissions({ '${permission}': … }) or can('${permission}') on the action`,
-        ]);
+    decide(query): AdminDecision {
+      const policy = Object.hasOwn(input.policies, query.permission)
+        ? input.policies[query.permission]
+        : undefined;
+      if (policy !== undefined) {
+        return evaluated(query.permission, policy, query.actor, query.subject);
       }
-      return evaluated(permission, policy, actor, subject);
+      const decision = decideByRoleMap(query);
+      const by = `no policy mapped for "${query.permission}": decided by the role map`;
+      return { ...decision, trace: [by, ...decision.trace] };
     },
   };
 }