@byline/admin 2.4.0 → 2.4.1

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

@@ -0,0 +1,137 @@
+/**
+ * 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 { AbilityRegistry } from '@byline/auth'
+
+import { toAbilityDescriptor } from './dto.js'
+import {
+  ERR_ADMIN_PERMISSIONS_ABILITY_UNREGISTERED,
+  ERR_ADMIN_PERMISSIONS_ROLE_NOT_FOUND,
+} from './errors.js'
+import type { AdminStore } from '../../store.js'
+import type {
+  GetRoleAbilitiesRequest,
+  GetRoleAbilitiesResponse,
+  ListRegisteredAbilitiesResponse,
+  SetRoleAbilitiesRequest,
+  SetRoleAbilitiesResponse,
+  WhoHasAbilityRequest,
+  WhoHasAbilityResponse,
+} from './schemas.js'
+
+/**
+ * Read-only inspector service for admin-permissions.
+ *
+ * Two responsibilities:
+ *
+ *   1. **Enumerate registered abilities.** Pure registry read — no DB
+ *      access. The registry is populated at `initBylineCore()` time
+ *      by collection auto-registration plus subsystem registrars
+ *      (`registerAdminAbilities`).
+ *   2. **Resolve the who-has matrix.** For a given ability key, list
+ *      the roles that grant it and the distinct admin users
+ *      transitively holding it. Backed by two single-query joins on
+ *      the permissions repository, then resolved against the roles
+ *      and users repositories so the inspector can render names
+ *      without further round-trips.
+ *
+ * The editor surface (`getRoleAbilities` / `setRoleAbilities`) is
+ * deliberately not on this service yet — it lands with Phase B and
+ * will live alongside these methods.
+ */
+export class AdminPermissionsService {
+  readonly #store: AdminStore
+  readonly #abilities: AbilityRegistry
+
+  constructor(deps: { store: AdminStore; abilities: AbilityRegistry }) {
+    this.#store = deps.store
+    this.#abilities = deps.abilities
+  }
+
+  listRegisteredAbilities(): ListRegisteredAbilitiesResponse {
+    const flat = this.#abilities.list().map(toAbilityDescriptor)
+    // Re-bucket from the same shaped descriptors so flat and groups
+    // stay byte-identical apart from grouping. Iteration order matches
+    // registration order — the registry's `byGroup` already preserves
+    // insertion order.
+    const grouped = this.#abilities.byGroup()
+    const groups = Array.from(grouped.entries(), ([group, abilities]) => ({
+      group,
+      abilities: abilities.map(toAbilityDescriptor),
+    }))
+    return {
+      abilities: flat,
+      groups,
+      total: flat.length,
+    }
+  }
+
+  async getRoleAbilities(request: GetRoleAbilitiesRequest): Promise<GetRoleAbilitiesResponse> {
+    const role = await this.#store.adminRoles.getById(request.id)
+    if (!role) throw ERR_ADMIN_PERMISSIONS_ROLE_NOT_FOUND()
+    const abilities = await this.#store.adminPermissions.listAbilities(request.id)
+    return { roleId: request.id, abilities }
+  }
+
+  async setRoleAbilities(request: SetRoleAbilitiesRequest): Promise<SetRoleAbilitiesResponse> {
+    const role = await this.#store.adminRoles.getById(request.id)
+    if (!role) throw ERR_ADMIN_PERMISSIONS_ROLE_NOT_FOUND()
+
+    // Reject any ability that is not in the registry — guards against
+    // typos, stale UI state, and a since-removed plugin's keys lingering
+    // in someone's draft. The registry was populated at init time so
+    // this is an in-memory check.
+    const unknown = request.abilities.filter((key) => !this.#abilities.has(key))
+    if (unknown.length > 0) {
+      throw ERR_ADMIN_PERMISSIONS_ABILITY_UNREGISTERED({
+        message: `Unregistered abilities: ${unknown.join(', ')}`,
+      })
+    }
+
+    // Wholesale-replace inside a transaction (handled by the repo).
+    await this.#store.adminPermissions.setAbilities(request.id, request.abilities)
+    // Return the freshly-stored set so the client can reset its dirty
+    // state without a second round-trip — also defends against drift if
+    // the repo dedupes or reorders.
+    const stored = await this.#store.adminPermissions.listAbilities(request.id)
+    return { roleId: request.id, abilities: stored }
+  }
+
+  async whoHasAbility(request: WhoHasAbilityRequest): Promise<WhoHasAbilityResponse> {
+    // Run the two inverse joins in parallel — they read the same table
+    // through different join paths but neither blocks the other.
+    const [roleIds, userIds] = await Promise.all([
+      this.#store.adminPermissions.listRolesForAbility(request.ability),
+      this.#store.adminPermissions.listUsersForAbility(request.ability),
+    ])
+
+    // Resolve role + user metadata in parallel batches. We accept the
+    // N round-trips here because admin role and user counts are small
+    // by design; if they grow we add `getByIds(ids[])` repo methods
+    // later.
+    const [roles, users] = await Promise.all([
+      Promise.all(roleIds.map((id) => this.#store.adminRoles.getById(id))),
+      Promise.all(userIds.map((id) => this.#store.adminUsers.getById(id))),
+    ])
+
+    return {
+      ability: request.ability,
+      roles: roles
+        .filter((r): r is NonNullable<typeof r> => r != null)
+        .map((r) => ({ id: r.id, name: r.name, machine_name: r.machine_name })),
+      users: users
+        .filter((u): u is NonNullable<typeof u> => u != null)
+        .map((u) => ({
+          id: u.id,
+          email: u.email,
+          given_name: u.given_name,
+          family_name: u.family_name,
+        })),
+    }
+  }
+}

package/src/modules/admin-roles/abilities.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 { AbilityRegistry } from '@byline/auth'
+
+/**
+ * Ability keys for the admin-roles module.
+ *
+ * Reorder is intentionally **rolled into `update`** — same trust level
+ * (mutating role identity), and splitting it would force a redundant
+ * `reorder` permission alongside `update` for every role-managing role.
+ *
+ * Per-role ability grants are managed by the sibling
+ * `@byline/admin/admin-permissions` module and have their own ability
+ * keys there.
+ */
+export const ADMIN_ROLES_ABILITIES = {
+  read: 'admin.roles.read',
+  create: 'admin.roles.create',
+  update: 'admin.roles.update',
+  delete: 'admin.roles.delete',
+} as const
+
+export type AdminRolesAbilityKey =
+  (typeof ADMIN_ROLES_ABILITIES)[keyof typeof ADMIN_ROLES_ABILITIES]
+
+/**
+ * Register every admin-roles ability with the framework's `AbilityRegistry`.
+ * Called from `registerAdminAbilities(registry)` at package level, which
+ * the webapp wires into `initBylineCore()`.
+ */
+export function registerAdminRolesAbilities(registry: AbilityRegistry): void {
+  registry.register({
+    key: ADMIN_ROLES_ABILITIES.read,
+    label: 'Read admin roles',
+    group: 'admin.roles',
+    source: 'admin',
+  })
+  registry.register({
+    key: ADMIN_ROLES_ABILITIES.create,
+    label: 'Create admin roles',
+    group: 'admin.roles',
+    source: 'admin',
+  })
+  registry.register({
+    key: ADMIN_ROLES_ABILITIES.update,
+    label: 'Update or reorder admin roles',
+    group: 'admin.roles',
+    source: 'admin',
+  })
+  registry.register({
+    key: ADMIN_ROLES_ABILITIES.delete,
+    label: 'Delete admin roles',
+    group: 'admin.roles',
+    source: 'admin',
+  })
+}

package/src/modules/admin-roles/commands.ts

@@ -0,0 +1,161 @@
+/**
+ * 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 Command, createCommand } from '../../lib/create-command.js'
+import { ADMIN_USERS_ABILITIES } from '../admin-users/abilities.js'
+import { ADMIN_ROLES_ABILITIES } from './abilities.js'
+import {
+  adminRoleListResponseSchema,
+  adminRoleResponseSchema,
+  createAdminRoleRequestSchema,
+  deleteAdminRoleRequestSchema,
+  getAdminRoleRequestSchema,
+  getRolesForUserRequestSchema,
+  listAdminRolesRequestSchema,
+  okResponseSchema,
+  reorderAdminRolesRequestSchema,
+  setRolesForUserRequestSchema,
+  updateAdminRoleRequestSchema,
+  userRolesResponseSchema,
+} from './schemas.js'
+import { AdminRolesService } from './service.js'
+import type { AdminStore } from '../../store.js'
+import type {
+  AdminRoleListResponse,
+  AdminRoleResponse,
+  CreateAdminRoleRequest,
+  DeleteAdminRoleRequest,
+  GetAdminRoleRequest,
+  GetRolesForUserRequest,
+  ListAdminRolesRequest,
+  OkResponse,
+  ReorderAdminRolesRequest,
+  SetRolesForUserRequest,
+  UpdateAdminRoleRequest,
+  UserRolesResponse,
+} from './schemas.js'
+
+/**
+ * Transport-agnostic commands for the admin-roles module.
+ *
+ * Every command goes through `createCommand`, which folds the four
+ * standard steps (validate → assert admin actor + ability → invoke
+ * service → validate output) into one declaration.
+ *
+ * Reorder uses the `update` ability — see `abilities.ts` for the
+ * rationale (same trust level as content updates; splitting it would
+ * force a redundant key on every role-managing role).
+ */
+
+export interface AdminRolesCommandDeps {
+  store: AdminStore
+}
+
+function serviceOf(deps: AdminRolesCommandDeps): AdminRolesService {
+  return new AdminRolesService({ store: deps.store })
+}
+
+export const listAdminRolesCommand: Command<
+  ListAdminRolesRequest,
+  AdminRoleListResponse,
+  AdminRolesCommandDeps
+> = createCommand({
+  method: 'listAdminRoles',
+  auth: { ability: ADMIN_ROLES_ABILITIES.read },
+  schemas: { input: listAdminRolesRequestSchema, output: adminRoleListResponseSchema },
+  handler: ({ deps }) => serviceOf(deps).listRoles(),
+})
+
+export const getAdminRoleCommand: Command<
+  GetAdminRoleRequest,
+  AdminRoleResponse,
+  AdminRolesCommandDeps
+> = createCommand({
+  method: 'getAdminRole',
+  auth: { ability: ADMIN_ROLES_ABILITIES.read },
+  schemas: { input: getAdminRoleRequestSchema, output: adminRoleResponseSchema },
+  handler: ({ input, deps }) => serviceOf(deps).getRole(input),
+})
+
+export const createAdminRoleCommand: Command<
+  CreateAdminRoleRequest,
+  AdminRoleResponse,
+  AdminRolesCommandDeps
+> = createCommand({
+  method: 'createAdminRole',
+  auth: { ability: ADMIN_ROLES_ABILITIES.create },
+  schemas: { input: createAdminRoleRequestSchema, output: adminRoleResponseSchema },
+  handler: ({ input, deps }) => serviceOf(deps).createRole(input),
+})
+
+export const updateAdminRoleCommand: Command<
+  UpdateAdminRoleRequest,
+  AdminRoleResponse,
+  AdminRolesCommandDeps
+> = createCommand({
+  method: 'updateAdminRole',
+  auth: { ability: ADMIN_ROLES_ABILITIES.update },
+  schemas: { input: updateAdminRoleRequestSchema, output: adminRoleResponseSchema },
+  handler: ({ input, deps }) => serviceOf(deps).updateRole(input),
+})
+
+export const deleteAdminRoleCommand: Command<
+  DeleteAdminRoleRequest,
+  OkResponse,
+  AdminRolesCommandDeps
+> = createCommand({
+  method: 'deleteAdminRole',
+  auth: { ability: ADMIN_ROLES_ABILITIES.delete },
+  schemas: { input: deleteAdminRoleRequestSchema, output: okResponseSchema },
+  handler: async ({ input, deps }) => {
+    await serviceOf(deps).deleteRole(input)
+    return { ok: true } as const
+  },
+})
+
+export const reorderAdminRolesCommand: Command<
+  ReorderAdminRolesRequest,
+  OkResponse,
+  AdminRolesCommandDeps
+> = createCommand({
+  method: 'reorderAdminRoles',
+  auth: { ability: ADMIN_ROLES_ABILITIES.update },
+  schemas: { input: reorderAdminRolesRequestSchema, output: okResponseSchema },
+  handler: async ({ input, deps }) => {
+    await serviceOf(deps).reorderRoles(input)
+    return { ok: true } as const
+  },
+})
+
+export const getRolesForUserCommand: Command<
+  GetRolesForUserRequest,
+  UserRolesResponse,
+  AdminRolesCommandDeps
+> = createCommand({
+  method: 'getRolesForUser',
+  // Reading a user's role assignments requires read access to admin
+  // users — the data is fundamentally about that user.
+  auth: { ability: ADMIN_USERS_ABILITIES.read },
+  schemas: { input: getRolesForUserRequestSchema, output: userRolesResponseSchema },
+  handler: ({ input, deps }) => serviceOf(deps).getRolesForUser(input),
+})
+
+export const setRolesForUserCommand: Command<
+  SetRolesForUserRequest,
+  UserRolesResponse,
+  AdminRolesCommandDeps
+> = createCommand({
+  method: 'setRolesForUser',
+  // Editing a user's role-set is at the same trust level as updating
+  // their other admin fields. Roll into `admin.users.update` rather
+  // than minting a separate `admin.users.assignRoles` key — the role
+  // editor's checkbox tree would otherwise need both.
+  auth: { ability: ADMIN_USERS_ABILITIES.update },
+  schemas: { input: setRolesForUserRequestSchema, output: userRolesResponseSchema },
+  handler: ({ input, deps }) => serviceOf(deps).setRolesForUser(input),
+})

package/src/modules/admin-roles/components/create.module.css

@@ -0,0 +1,40 @@
+/**
+ * CreateAdminRole — drawer form for creating a new role.
+ *
+ * Override handles:
+ *   .byline-role-create-wrap     — outer container
+ *   .byline-role-create-form     — vertical-stack form element
+ *   .byline-role-create-actions  — Cancel/Save row
+ *   .byline-role-create-action   — buttons in the actions row
+ */
+
+.wrap,
+:global(.byline-role-create-wrap) {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-8);
+  padding: var(--spacing-4);
+  margin-top: var(--spacing-4);
+}
+
+.form,
+:global(.byline-role-create-form) {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-16);
+  padding-top: var(--spacing-8);
+}
+
+.actions,
+:global(.byline-role-create-actions) {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--spacing-8);
+  margin-top: var(--spacing-16);
+}
+
+.action,
+:global(.byline-role-create-action) {
+  min-width: 4rem;
+}

package/src/modules/admin-roles/components/create.tsx

@@ -0,0 +1,218 @@
+'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
+ */
+
+/**
+ * Create-admin-role drawer form.
+ *
+ * Same TanStack Form + Zod shape as the admin-users equivalent. The
+ * `machine_name` field is captured at create time only — it is the
+ * stable code-side handle for the role and is immutable thereafter
+ * (see the repository contract).
+ */
+
+import { useState } from 'react'
+import { revalidateLogic, useForm } from '@tanstack/react-form-start'
+
+import { Alert, Button, Input, LoaderEllipsis, TextArea } from '@byline/ui/react'
+import cx from 'classnames'
+import { z } from 'zod'
+
+import { useBylineAdminServices } from '../../../services/admin-services-context.js'
+import styles from './create.module.css'
+import type { AdminRoleResponse } from '../index.js'
+
+const createAdminRoleFormSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(128, 'Name must not exceed 128 characters'),
+  machine_name: z
+    .string()
+    .min(1, 'Machine name is required')
+    .max(128, 'Machine name must not exceed 128 characters')
+    .regex(/^[a-z0-9][a-z0-9_-]*$/, {
+      message: 'Lowercase letters, numbers, hyphens, and underscores only',
+    }),
+  description: z.string().max(2000, 'Description must not exceed 2000 characters'),
+})
+
+type CreateAdminRoleValues = z.infer<typeof createAdminRoleFormSchema>
+
+const initialValues: CreateAdminRoleValues = {
+  name: '',
+  machine_name: '',
+  description: '',
+}
+
+function normaliseText(value: string): string | null {
+  return value.trim().length > 0 ? value : null
+}
+
+interface CreateAdminRoleProps {
+  onClose?: () => void
+  onSuccess?: (role: AdminRoleResponse) => void
+}
+
+export function CreateAdminRole({ onClose, onSuccess }: CreateAdminRoleProps) {
+  const { createAdminRole } = useBylineAdminServices()
+  const [formError, setFormError] = useState<string | null>(null)
+
+  const form = useForm({
+    defaultValues: initialValues,
+    validationLogic: revalidateLogic({
+      mode: 'blur',
+      modeAfterSubmission: 'change',
+    }),
+    validators: {
+      onDynamic: createAdminRoleFormSchema,
+    },
+    onSubmit: async ({ value }) => {
+      setFormError(null)
+      try {
+        const created = await createAdminRole({
+          data: {
+            name: value.name.trim(),
+            machine_name: value.machine_name.trim(),
+            description: normaliseText(value.description),
+          },
+        })
+        form.reset(initialValues)
+        onSuccess?.(created)
+      } catch (err) {
+        const code = getErrorCode(err)
+        if (code === 'admin.roles.machineNameInUse') {
+          form.setFieldMeta('machine_name', (meta) => ({
+            ...meta,
+            errorMap: { ...meta.errorMap, onServer: 'This machine name is already in use.' },
+            errors: ['This machine name is already in use.'],
+          }))
+          return
+        }
+        setFormError('Could not create this admin role. Please try again.')
+      }
+    },
+  })
+
+  return (
+    <div className={cx('byline-role-create-wrap', styles.wrap)}>
+      <form
+        noValidate
+        onSubmit={(event) => {
+          event.preventDefault()
+          event.stopPropagation()
+          void form.handleSubmit()
+        }}
+        className={cx('byline-role-create-form', styles.form)}
+      >
+        {formError ? <Alert intent="danger">{formError}</Alert> : null}
+
+        <form.Field name="name">
+          {(field) => (
+            <Input
+              label="Name"
+              id="new-role-name"
+              name={field.name}
+              value={field.state.value}
+              onBlur={field.handleBlur}
+              onChange={(e) => field.handleChange(e.currentTarget.value)}
+              error={field.state.meta.errors.length > 0}
+              errorText={firstError(field.state.meta.errors)}
+              helpText="Human-readable label, e.g. 'Editor'."
+              required
+            />
+          )}
+        </form.Field>
+
+        <form.Field name="machine_name">
+          {(field) => (
+            <Input
+              label="Machine name"
+              id="new-role-machine-name"
+              name={field.name}
+              value={field.state.value}
+              onBlur={field.handleBlur}
+              onChange={(e) => field.handleChange(e.currentTarget.value)}
+              error={field.state.meta.errors.length > 0}
+              errorText={firstError(field.state.meta.errors)}
+              helpText="Stable code-side handle, e.g. 'editor'. Cannot be changed later."
+              required
+            />
+          )}
+        </form.Field>
+
+        <form.Field name="description">
+          {(field) => (
+            <TextArea
+              label="Description"
+              id="new-role-description"
+              name={field.name}
+              value={field.state.value}
+              onBlur={field.handleBlur}
+              onChange={(e) => field.handleChange(e.currentTarget.value)}
+              error={field.state.meta.errors.length > 0}
+              errorText={firstError(field.state.meta.errors)}
+              rows={3}
+            />
+          )}
+        </form.Field>
+
+        <div className={cx('byline-role-create-actions', styles.actions)}>
+          <Button
+            type="button"
+            intent="secondary"
+            size="sm"
+            onClick={onClose}
+            className={cx('byline-role-create-action', styles.action)}
+          >
+            Cancel
+          </Button>
+          <form.Subscribe
+            selector={(state) => ({
+              canSubmit: state.canSubmit,
+              isSubmitting: state.isSubmitting,
+            })}
+          >
+            {({ canSubmit, isSubmitting }) => (
+              <Button
+                size="sm"
+                intent="primary"
+                type="submit"
+                disabled={!canSubmit || isSubmitting}
+                className={cx('byline-role-create-action', styles.action)}
+              >
+                {isSubmitting === true ? <LoaderEllipsis size={42} /> : 'Save'}
+              </Button>
+            )}
+          </form.Subscribe>
+        </div>
+      </form>
+    </div>
+  )
+}
+
+function firstError(errors: readonly unknown[]): string | undefined {
+  for (const err of errors) {
+    if (typeof err === 'string') return err
+    if (err && typeof err === 'object' && 'message' in err) {
+      const msg = (err as { message?: unknown }).message
+      if (typeof msg === 'string') return msg
+    }
+  }
+  return undefined
+}
+
+function getErrorCode(err: unknown): string | null {
+  if (err && typeof err === 'object') {
+    const e = err as { code?: unknown; cause?: unknown }
+    if (typeof e.code === 'string') return e.code
+    if (e.cause && typeof e.cause === 'object' && 'code' in e.cause) {
+      const cause = e.cause as { code?: unknown }
+      if (typeof cause.code === 'string') return cause.code
+    }
+  }
+  return null
+}