@byline/admin 2.4.0 → 2.4.1

package/src/modules/admin-permissions/components/inspector.tsx

@@ -0,0 +1,298 @@
+'use client'
+
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Read-only abilities inspector — see docs/AUTHN-AUTHZ.md.
+ *
+ * Top level: a collapsible group per ability source (collections.docs,
+ * admin.users, etc.), each containing the abilities that group
+ * registered. Group buckets and ordering come straight from the
+ * `AbilityRegistry.byGroup()` shape (registration order preserved).
+ *
+ * Per-ability: an inline-expandable row showing the roles that grant
+ * the ability and the distinct admin users who hold it transitively.
+ * The matrix is fetched lazily on first expand and cached for the
+ * lifetime of the page — the registry is small (~40 keys) but the
+ * matrix queries are not free, and most visitors only inspect a few
+ * keys.
+ *
+ * Stable override handles: see `inspector.module.css`.
+ */
+
+import { useState } from 'react'
+
+import { Button, Container, LoaderRing, Section } from '@byline/ui/react'
+import cx from 'classnames'
+
+import { useBylineAdminServices } from '../../../services/admin-services-context.js'
+import styles from './inspector.module.css'
+import type {
+  AbilityDescriptorResponse,
+  AbilityGroupResponse,
+  ListRegisteredAbilitiesResponse,
+  WhoHasAbilityResponse,
+} from '../index.js'
+
+// --- helpers ---------------------------------------------------------------
+
+function sourceVariant(source: AbilityDescriptorResponse['source']) {
+  switch (source) {
+    case 'collection':
+      return {
+        global: 'byline-inspector-row-source-collection',
+        local: styles['row-source-collection'],
+      }
+    case 'admin':
+      return {
+        global: 'byline-inspector-row-source-admin',
+        local: styles['row-source-admin'],
+      }
+    case 'plugin':
+      return {
+        global: 'byline-inspector-row-source-plugin',
+        local: styles['row-source-plugin'],
+      }
+    case 'core':
+      return {
+        global: 'byline-inspector-row-source-core',
+        local: styles['row-source-core'],
+      }
+    default:
+      return {
+        global: 'byline-inspector-row-source-unknown',
+        local: styles['row-source-unknown'],
+      }
+  }
+}
+
+function displayUser(user: WhoHasAbilityResponse['users'][number]): string {
+  const parts = [user.given_name, user.family_name].filter(
+    (p): p is string => typeof p === 'string' && p.length > 0
+  )
+  return parts.length > 0 ? `${parts.join(' ')} (${user.email})` : user.email
+}
+
+// --- expandable matrix row ------------------------------------------------
+
+function MatrixPanel({ matrix }: { matrix: WhoHasAbilityResponse }) {
+  return (
+    <div className={cx('byline-inspector-matrix', styles.matrix)}>
+      <div>
+        <h4 className={cx('byline-inspector-matrix-title', styles['matrix-title'])}>
+          Roles ({matrix.roles.length})
+        </h4>
+        {matrix.roles.length === 0 ? (
+          <p className={cx('muted', 'byline-inspector-matrix-empty', styles['matrix-empty'])}>
+            No role grants this ability.
+          </p>
+        ) : (
+          <ul className={cx('byline-inspector-matrix-list', styles['matrix-list'])}>
+            {matrix.roles.map((role) => (
+              <li
+                key={role.id}
+                className={cx('byline-inspector-matrix-item', styles['matrix-item'])}
+              >
+                <span className={cx('byline-inspector-matrix-name', styles['matrix-name'])}>
+                  {role.name}
+                </span>
+                <span className="muted">&nbsp;·&nbsp;{role.machine_name}</span>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+      <div>
+        <h4 className={cx('byline-inspector-matrix-title', styles['matrix-title'])}>
+          Admin users ({matrix.users.length})
+        </h4>
+        {matrix.users.length === 0 ? (
+          <p className={cx('muted', 'byline-inspector-matrix-empty', styles['matrix-empty'])}>
+            No admin user holds this ability.
+          </p>
+        ) : (
+          <ul className={cx('byline-inspector-matrix-list', styles['matrix-list'])}>
+            {matrix.users.map((user) => (
+              <li
+                key={user.id}
+                className={cx('byline-inspector-matrix-item', styles['matrix-item'])}
+              >
+                {displayUser(user)}
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </div>
+  )
+}
+
+interface AbilityRowProps {
+  ability: AbilityDescriptorResponse
+  matrix: WhoHasAbilityResponse | undefined
+  loading: boolean
+  onToggle: () => void
+  expanded: boolean
+}
+
+function AbilityRow({ ability, matrix, loading, onToggle, expanded }: AbilityRowProps) {
+  const sv = sourceVariant(ability.source)
+  return (
+    <div className={cx('byline-inspector-row', styles.row)}>
+      <div className={cx('byline-inspector-row-head', styles['row-head'])}>
+        <div className={cx('byline-inspector-row-info', styles['row-info'])}>
+          <div className={cx('byline-inspector-row-meta', styles['row-meta'])}>
+            <code className={cx('byline-inspector-row-key', styles['row-key'])}>{ability.key}</code>
+            <span
+              className={cx(
+                'byline-inspector-row-source',
+                styles['row-source'],
+                sv.global,
+                sv.local
+              )}
+            >
+              {ability.source ?? 'unknown'}
+            </span>
+          </div>
+          <p className={cx('byline-inspector-row-label', styles['row-label'])}>{ability.label}</p>
+          {ability.description ? (
+            <p
+              className={cx('muted', 'byline-inspector-row-description', styles['row-description'])}
+            >
+              {ability.description}
+            </p>
+          ) : null}
+        </div>
+        <Button size="xs" intent="secondary" onClick={onToggle}>
+          {expanded ? 'Hide' : 'Holders'}
+        </Button>
+      </div>
+      {expanded ? (
+        loading ? (
+          <div className={cx('byline-inspector-loader', styles.loader)}>
+            <LoaderRing size={20} color="#888" />
+            <span className="muted">Loading…</span>
+          </div>
+        ) : matrix ? (
+          <MatrixPanel matrix={matrix} />
+        ) : null
+      ) : null}
+    </div>
+  )
+}
+
+// --- group section --------------------------------------------------------
+
+interface GroupSectionProps {
+  group: AbilityGroupResponse
+  matrices: Record<string, WhoHasAbilityResponse>
+  loading: Set<string>
+  expanded: Set<string>
+  onToggle: (abilityKey: string) => void
+}
+
+function GroupSection({ group, matrices, loading, expanded, onToggle }: GroupSectionProps) {
+  return (
+    <details open className={cx('byline-inspector-group', styles.group)}>
+      <summary className={cx('byline-inspector-group-summary', styles['group-summary'])}>
+        <span className={cx('byline-inspector-group-name', styles['group-name'])}>
+          {group.group}
+        </span>
+        <span className={cx('muted', 'byline-inspector-group-count', styles['group-count'])}>
+          {group.abilities.length} abilities
+        </span>
+      </summary>
+      <div className={cx('byline-inspector-group-body', styles['group-body'])}>
+        {group.abilities.map((ability) => (
+          <AbilityRow
+            key={ability.key}
+            ability={ability}
+            matrix={matrices[ability.key]}
+            loading={loading.has(ability.key)}
+            expanded={expanded.has(ability.key)}
+            onToggle={() => onToggle(ability.key)}
+          />
+        ))}
+      </div>
+    </details>
+  )
+}
+
+// --- top level ------------------------------------------------------------
+
+export function AbilitiesInspector({ data }: { data: ListRegisteredAbilitiesResponse }) {
+  const { whoHasAbility } = useBylineAdminServices()
+  const [expanded, setExpanded] = useState<Set<string>>(new Set())
+  const [loading, setLoading] = useState<Set<string>>(new Set())
+  const [matrices, setMatrices] = useState<Record<string, WhoHasAbilityResponse>>({})
+
+  async function handleToggle(abilityKey: string): Promise<void> {
+    setExpanded((current) => {
+      const next = new Set(current)
+      if (next.has(abilityKey)) {
+        next.delete(abilityKey)
+      } else {
+        next.add(abilityKey)
+      }
+      return next
+    })
+
+    // Lazy-load the matrix the first time a row expands. Cached for
+    // the lifetime of the page after that.
+    if (!matrices[abilityKey] && !loading.has(abilityKey)) {
+      setLoading((current) => new Set(current).add(abilityKey))
+      try {
+        const result = await whoHasAbility({ data: { ability: abilityKey } })
+        setMatrices((current) => ({ ...current, [abilityKey]: result }))
+      } finally {
+        setLoading((current) => {
+          const next = new Set(current)
+          next.delete(abilityKey)
+          return next
+        })
+      }
+    }
+  }
+
+  return (
+    <Section>
+      <Container>
+        <div className={cx('byline-inspector-head', styles.head)}>
+          <h1 className={cx('byline-inspector-title', styles.title)}>Abilities Inspector</h1>
+          <span className={cx('byline-inspector-count-pill', styles['count-pill'])}>
+            {data.total} registered
+          </span>
+        </div>
+        <p className={cx('muted', 'byline-inspector-lead', styles.lead)}>
+          Read-only view of every ability registered through <code>bylineCore.abilities</code>.
+          Collections auto-register CRUD + workflow abilities; admin subsystems contribute their own
+          keys at composition root via <code>registerAdminAbilities</code>.
+        </p>
+        {data.groups.length === 0 ? (
+          <p className={cx('muted', 'byline-inspector-empty', styles.empty)}>
+            No abilities are registered.
+          </p>
+        ) : (
+          <div className={cx('byline-inspector-groups', styles.groups)}>
+            {data.groups.map((group) => (
+              <GroupSection
+                key={group.group}
+                group={group}
+                matrices={matrices}
+                loading={loading}
+                expanded={expanded}
+                onToggle={(key) => void handleToggle(key)}
+              />
+            ))}
+          </div>
+        )}
+      </Container>
+    </Section>
+  )
+}

package/src/modules/admin-permissions/dto.ts

@@ -0,0 +1,28 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type { AbilityDescriptor } from '@byline/auth'
+
+import type { AbilityDescriptorResponse } from './schemas.js'
+
+/**
+ * Shape an `AbilityDescriptor` from the registry into its public
+ * response form. Identity-shaped today — the indirection exists so
+ * that future internal-only fields on `AbilityDescriptor` (e.g. a
+ * registration timestamp) stay opted out of the public shape by
+ * default.
+ */
+export function toAbilityDescriptor(descriptor: AbilityDescriptor): AbilityDescriptorResponse {
+  return {
+    key: descriptor.key,
+    label: descriptor.label,
+    description: descriptor.description ?? null,
+    group: descriptor.group,
+    source: descriptor.source ?? null,
+  }
+}

package/src/modules/admin-permissions/errors.ts

@@ -0,0 +1,57 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Module-local error codes for admin-permissions.
+ *
+ * `ROLE_NOT_FOUND` covers the editor (and future grant/revoke) paths;
+ * `ABILITY_UNREGISTERED` is reserved for the editor too — when a client
+ * tries to grant an ability key that no subsystem has registered. The
+ * inspector is read-only and never throws either of these.
+ */
+
+export const AdminPermissionsErrorCodes = {
+  ROLE_NOT_FOUND: 'admin.permissions.roleNotFound',
+  ABILITY_UNREGISTERED: 'admin.permissions.abilityUnregistered',
+} as const
+
+export type AdminPermissionsErrorCode =
+  (typeof AdminPermissionsErrorCodes)[keyof typeof AdminPermissionsErrorCodes]
+
+export interface AdminPermissionsErrorOptions {
+  message?: string
+  cause?: unknown
+}
+
+export class AdminPermissionsError extends Error {
+  public readonly code: AdminPermissionsErrorCode
+
+  constructor(code: AdminPermissionsErrorCode, options: { message: string; cause?: unknown }) {
+    super(options.message, options.cause != null ? { cause: options.cause } : undefined)
+    this.name = 'AdminPermissionsError'
+    this.code = code
+  }
+}
+
+const make =
+  (code: AdminPermissionsErrorCode, defaultMessage: string) =>
+  (options?: AdminPermissionsErrorOptions): AdminPermissionsError =>
+    new AdminPermissionsError(code, {
+      message: options?.message ?? defaultMessage,
+      cause: options?.cause,
+    })
+
+export const ERR_ADMIN_PERMISSIONS_ROLE_NOT_FOUND = make(
+  AdminPermissionsErrorCodes.ROLE_NOT_FOUND,
+  'admin role not found'
+)
+
+export const ERR_ADMIN_PERMISSIONS_ABILITY_UNREGISTERED = make(
+  AdminPermissionsErrorCodes.ABILITY_UNREGISTERED,
+  'one or more abilities are not registered'
+)

package/src/modules/admin-permissions/index.ts

@@ -0,0 +1,72 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * `@byline/admin/admin-permissions` — ability grants against roles plus
+ * the read-only inspector view.
+ *
+ * Backs the `byline_admin_permissions` table. Ability keys are
+ * registered at `initBylineCore()` time through the `AbilityRegistry`
+ * from `@byline/auth`; this module owns the per-role grant data and the
+ * inspector that surfaces it.
+ *
+ * The editor surface (`getRoleAbilities` / `setRoleAbilities`) is
+ * deliberately out of scope on this first ship — it lands with Phase B
+ * and mounts on the admin-roles role detail page.
+ */
+
+export {
+  ADMIN_PERMISSIONS_ABILITIES,
+  type AdminPermissionsAbilityKey,
+  registerAdminPermissionsAbilities,
+} from './abilities.js'
+export {
+  getRoleAbilitiesCommand,
+  listRegisteredAbilitiesCommand,
+  setRoleAbilitiesCommand,
+  whoHasAbilityCommand,
+} from './commands.js'
+export { toAbilityDescriptor } from './dto.js'
+export {
+  AdminPermissionsError,
+  type AdminPermissionsErrorCode,
+  AdminPermissionsErrorCodes,
+  ERR_ADMIN_PERMISSIONS_ABILITY_UNREGISTERED,
+  ERR_ADMIN_PERMISSIONS_ROLE_NOT_FOUND,
+} from './errors.js'
+export {
+  abilityDescriptorResponseSchema,
+  abilityGroupResponseSchema,
+  abilityHolderRoleSchema,
+  abilityHolderUserSchema,
+  getRoleAbilitiesRequestSchema,
+  getRoleAbilitiesResponseSchema,
+  listRegisteredAbilitiesRequestSchema,
+  listRegisteredAbilitiesResponseSchema,
+  setRoleAbilitiesRequestSchema,
+  setRoleAbilitiesResponseSchema,
+  whoHasAbilityRequestSchema,
+  whoHasAbilityResponseSchema,
+} from './schemas.js'
+export { AdminPermissionsService } from './service.js'
+export type { AdminPermissionsCommandDeps } from './commands.js'
+export type { AdminPermissionsRepository } from './repository.js'
+export type {
+  AbilityDescriptorResponse,
+  AbilityGroupResponse,
+  AbilityHolderRole,
+  AbilityHolderUser,
+  GetRoleAbilitiesRequest,
+  GetRoleAbilitiesResponse,
+  ListRegisteredAbilitiesRequest,
+  ListRegisteredAbilitiesResponse,
+  SetRoleAbilitiesRequest,
+  SetRoleAbilitiesResponse,
+  WhoHasAbilityRequest,
+  WhoHasAbilityResponse,
+} from './schemas.js'

package/src/modules/admin-permissions/repository.ts

@@ -0,0 +1,49 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * `AdminPermissionsRepository` — ability grants against roles.
+ *
+ * Backs the `byline_admin_permissions` table — one row per (role, ability)
+ * grant. `setAbilities` is the wholesale-replace operation the role-ability
+ * editor in the admin UI will drive; `grantAbility` / `revokeAbility` are
+ * the incremental operations for programmatic callers.
+ *
+ * `listAbilitiesForUser` is the join used by `resolveActor` to build an
+ * `AdminAuth` — distinct abilities across every role the user holds.
+ *
+ * `listRolesForAbility` and `listUsersForAbility` are the inverse joins
+ * driving the admin-permissions inspector view (which roles grant a given
+ * ability, and which admin users hold those roles transitively).
+ */
+
+export interface AdminPermissionsRepository {
+  /** Grant an ability to a role. Idempotent via the unique constraint. */
+  grantAbility(roleId: string, ability: string): Promise<void>
+  revokeAbility(roleId: string, ability: string): Promise<void>
+  listAbilities(roleId: string): Promise<string[]>
+  /** Replace the ability set for a role wholesale. Runs inside a transaction. */
+  setAbilities(roleId: string, abilities: readonly string[]): Promise<void>
+  /**
+   * Distinct abilities granted to a user via every role they hold. Used by
+   * `resolveActor()` to build the ability set on an `AdminAuth`.
+   */
+  listAbilitiesForUser(userId: string): Promise<string[]>
+  /**
+   * Role ids that grant the given ability. Used by the inspector to render
+   * the per-ability "granted by these roles" list.
+   */
+  listRolesForAbility(ability: string): Promise<string[]>
+  /**
+   * Distinct admin user ids that hold a role granting the given ability.
+   * Single-query join through `byline_admin_role_admin_user` — preferred
+   * over chaining `listRolesForAbility` + `listUsersForRole` so the
+   * inspector stays O(1) queries per ability.
+   */
+  listUsersForAbility(ability: string): Promise<string[]>
+}

package/src/modules/admin-permissions/schemas.ts

@@ -0,0 +1,128 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { uuidSchema } from '@byline/core/validation'
+import { z } from 'zod'
+
+/**
+ * Zod request/response schemas for the admin-permissions inspector.
+ *
+ * The inspector ships two endpoints:
+ *
+ *   - `listRegisteredAbilities` — flat list + grouped buckets straight
+ *     out of the `AbilityRegistry`. No DB read.
+ *   - `whoHasAbility` — for a given ability key, the list of roles that
+ *     grant it and the distinct list of admin users transitively
+ *     holding it. Two DB joins.
+ *
+ * Phase B will add `getRoleAbilities` / `setRoleAbilities` for the
+ * per-role editor on the admin-roles detail page; both are deliberately
+ * out of scope here.
+ */
+
+const abilityKeySchema = z.string().min(1).max(128)
+
+// ---------------------------------------------------------------------------
+// Requests
+// ---------------------------------------------------------------------------
+
+export const listRegisteredAbilitiesRequestSchema = z.object({}).optional()
+export type ListRegisteredAbilitiesRequest = z.infer<typeof listRegisteredAbilitiesRequestSchema>
+
+export const whoHasAbilityRequestSchema = z.object({
+  ability: abilityKeySchema,
+})
+export type WhoHasAbilityRequest = z.infer<typeof whoHasAbilityRequestSchema>
+
+export const getRoleAbilitiesRequestSchema = z.object({
+  id: uuidSchema,
+})
+export type GetRoleAbilitiesRequest = z.infer<typeof getRoleAbilitiesRequestSchema>
+
+export const setRoleAbilitiesRequestSchema = z.object({
+  id: uuidSchema,
+  abilities: z.array(abilityKeySchema),
+})
+export type SetRoleAbilitiesRequest = z.infer<typeof setRoleAbilitiesRequestSchema>
+
+// ---------------------------------------------------------------------------
+// Responses
+// ---------------------------------------------------------------------------
+
+const abilitySourceSchema = z.enum(['collection', 'plugin', 'core', 'admin']).nullable()
+
+export const abilityDescriptorResponseSchema = z.object({
+  key: z.string(),
+  label: z.string(),
+  description: z.string().nullable(),
+  group: z.string(),
+  source: abilitySourceSchema,
+})
+export type AbilityDescriptorResponse = z.infer<typeof abilityDescriptorResponseSchema>
+
+export const abilityGroupResponseSchema = z.object({
+  group: z.string(),
+  abilities: z.array(abilityDescriptorResponseSchema),
+})
+export type AbilityGroupResponse = z.infer<typeof abilityGroupResponseSchema>
+
+/**
+ * Inspector list payload. Returns both the flat list and the grouped
+ * buckets so the UI can render either shape without re-bucketing.
+ */
+export const listRegisteredAbilitiesResponseSchema = z.object({
+  abilities: z.array(abilityDescriptorResponseSchema),
+  groups: z.array(abilityGroupResponseSchema),
+  total: z.number().int().min(0),
+})
+export type ListRegisteredAbilitiesResponse = z.infer<typeof listRegisteredAbilitiesResponseSchema>
+
+/**
+ * Who-has-ability matrix entry. Roles and users are surfaced in the
+ * same response so the inline-expand row in the inspector renders in
+ * one round-trip.
+ */
+export const abilityHolderRoleSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  machine_name: z.string(),
+})
+export type AbilityHolderRole = z.infer<typeof abilityHolderRoleSchema>
+
+export const abilityHolderUserSchema = z.object({
+  id: z.string(),
+  email: z.string(),
+  given_name: z.string().nullable(),
+  family_name: z.string().nullable(),
+})
+export type AbilityHolderUser = z.infer<typeof abilityHolderUserSchema>
+
+export const whoHasAbilityResponseSchema = z.object({
+  ability: z.string(),
+  roles: z.array(abilityHolderRoleSchema),
+  users: z.array(abilityHolderUserSchema),
+})
+export type WhoHasAbilityResponse = z.infer<typeof whoHasAbilityResponseSchema>
+
+/**
+ * Editor payloads. `roleId` is echoed back on both responses so the
+ * caller can match async writes against the role they were editing
+ * without holding the id separately. `abilities` is the authoritative
+ * stored set after the write.
+ */
+export const getRoleAbilitiesResponseSchema = z.object({
+  roleId: z.string(),
+  abilities: z.array(z.string()),
+})
+export type GetRoleAbilitiesResponse = z.infer<typeof getRoleAbilitiesResponseSchema>
+
+export const setRoleAbilitiesResponseSchema = z.object({
+  roleId: z.string(),
+  abilities: z.array(z.string()),
+})
+export type SetRoleAbilitiesResponse = z.infer<typeof setRoleAbilitiesResponseSchema>