@byline/admin 2.4.0 → 2.4.2

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

@@ -0,0 +1,136 @@
+/**
+ * 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 { toAdminRole } from './dto.js'
+import {
+  ERR_ADMIN_ROLE_MACHINE_NAME_IN_USE,
+  ERR_ADMIN_ROLE_NOT_FOUND,
+  ERR_ADMIN_ROLE_USER_NOT_FOUND,
+} from './errors.js'
+import type { AdminStore } from '../../store.js'
+import type {
+  AdminRoleListResponse,
+  AdminRoleResponse,
+  CreateAdminRoleRequest,
+  DeleteAdminRoleRequest,
+  GetAdminRoleRequest,
+  GetRolesForUserRequest,
+  ReorderAdminRolesRequest,
+  SetRolesForUserRequest,
+  UpdateAdminRoleRequest,
+  UserRolesResponse,
+} from './schemas.js'
+
+/**
+ * Business logic for administering admin roles.
+ *
+ * Owns four concerns the repository deliberately avoids:
+ *
+ *   1. **Domain invariants.** `machine_name` uniqueness pre-check on
+ *      create — the unique index is the ultimate backstop, but the
+ *      pre-check produces a clean domain error rather than a raw
+ *      Postgres code.
+ *   2. **DTO shaping.** Raw rows are shaped through `toAdminRole` so
+ *      the response contract is owned in one place.
+ *   3. **Optimistic-concurrency plumbing.** The repo gates writes on
+ *      `expectedVid`; the service threads it from the validated request
+ *      shape. Version conflicts surface as
+ *      `AdminRolesError(VERSION_CONFLICT)` from the adapter; the service
+ *      does not catch them.
+ *   4. **Cross-table validation.** The user-roles editor validates the
+ *      user and every referenced role exists before mutating the join
+ *      table — clean errors over raw FK violations.
+ *
+ * Roles do not need a self-target invariant the way users do
+ * (no "self-delete" concept), so role-CRUD service methods are
+ * actor-agnostic and the ability check at the command boundary is the
+ * only authorisation.
+ */
+export class AdminRolesService {
+  readonly #store: AdminStore
+
+  constructor(deps: { store: AdminStore }) {
+    this.#store = deps.store
+  }
+
+  async listRoles(): Promise<AdminRoleListResponse> {
+    const rows = await this.#store.adminRoles.list()
+    return { roles: rows.map(toAdminRole) }
+  }
+
+  async getRole(request: GetAdminRoleRequest): Promise<AdminRoleResponse> {
+    const row = await this.#store.adminRoles.getById(request.id)
+    if (!row) throw ERR_ADMIN_ROLE_NOT_FOUND()
+    return toAdminRole(row)
+  }
+
+  async createRole(request: CreateAdminRoleRequest): Promise<AdminRoleResponse> {
+    // Pre-check for machine_name conflict so the common case returns a
+    // domain-specific error rather than the raw unique-violation code.
+    const existing = await this.#store.adminRoles.getByMachineName(request.machine_name)
+    if (existing) throw ERR_ADMIN_ROLE_MACHINE_NAME_IN_USE()
+
+    const row = await this.#store.adminRoles.create({
+      name: request.name,
+      machine_name: request.machine_name,
+      description: request.description ?? null,
+      order: request.order,
+    })
+    return toAdminRole(row)
+  }
+
+  async updateRole(request: UpdateAdminRoleRequest): Promise<AdminRoleResponse> {
+    const current = await this.#store.adminRoles.getById(request.id)
+    if (!current) throw ERR_ADMIN_ROLE_NOT_FOUND()
+    const row = await this.#store.adminRoles.update(request.id, request.vid, request.patch)
+    return toAdminRole(row)
+  }
+
+  async deleteRole(request: DeleteAdminRoleRequest): Promise<void> {
+    const exists = await this.#store.adminRoles.getById(request.id)
+    if (!exists) throw ERR_ADMIN_ROLE_NOT_FOUND()
+    await this.#store.adminRoles.delete(request.id, request.vid)
+  }
+
+  async reorderRoles(request: ReorderAdminRolesRequest): Promise<void> {
+    await this.#store.adminRoles.reorder(request.ids)
+  }
+
+  async getRolesForUser(request: GetRolesForUserRequest): Promise<UserRolesResponse> {
+    const user = await this.#store.adminUsers.getById(request.userId)
+    if (!user) throw ERR_ADMIN_ROLE_USER_NOT_FOUND()
+    const rows = await this.#store.adminRoles.listRolesForUser(request.userId)
+    return { userId: request.userId, roles: rows.map(toAdminRole) }
+  }
+
+  async setRolesForUser(request: SetRolesForUserRequest): Promise<UserRolesResponse> {
+    const user = await this.#store.adminUsers.getById(request.userId)
+    if (!user) throw ERR_ADMIN_ROLE_USER_NOT_FOUND()
+
+    // Validate every referenced role exists. N round-trips, but role
+    // assignment payloads are small by design (typically < 10 roles)
+    // and surfacing a clean `notFound` beats a raw FK violation.
+    if (request.roleIds.length > 0) {
+      const found = await Promise.all(
+        request.roleIds.map((id) => this.#store.adminRoles.getById(id))
+      )
+      const missing = request.roleIds.filter((_, i) => found[i] == null)
+      if (missing.length > 0) {
+        throw ERR_ADMIN_ROLE_NOT_FOUND({
+          message: `One or more referenced roles do not exist: ${missing.join(', ')}`,
+        })
+      }
+    }
+
+    await this.#store.adminRoles.setRolesForUser(request.userId, request.roleIds)
+    // Return the freshly stored set, shaped — saves the editor a second
+    // round-trip and guards against any normalisation the repo might apply.
+    const stored = await this.#store.adminRoles.listRolesForUser(request.userId)
+    return { userId: request.userId, roles: stored.map(toAdminRole) }
+  }
+}

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

@@ -0,0 +1,76 @@
+/**
+ * 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-users module.
+ *
+ * Dot-notation rather than Modulus' colon-notation — keeps one consistent
+ * hierarchy across the whole platform alongside `collections.<path>.<verb>`
+ * from core.
+ *
+ * `changePassword` is split out from `update` deliberately: setting
+ * someone else's password is a higher-trust operation than editing their
+ * profile fields, and the role editor UI benefits from naming it
+ * explicitly. A role can grant `update` without implicitly granting
+ * `changePassword`.
+ *
+ * Self-service (changing *own* password, email, etc.) does **not** use
+ * any of these keys. That flow lives in the separate `account` module
+ * where the actor is the target by definition; the `admin.users.*` keys
+ * are strictly for administering other admin users.
+ */
+export const ADMIN_USERS_ABILITIES = {
+  read: 'admin.users.read',
+  create: 'admin.users.create',
+  update: 'admin.users.update',
+  delete: 'admin.users.delete',
+  changePassword: 'admin.users.changePassword',
+} as const
+
+export type AdminUsersAbilityKey =
+  (typeof ADMIN_USERS_ABILITIES)[keyof typeof ADMIN_USERS_ABILITIES]
+
+/**
+ * Register every admin-users ability with the framework's `AbilityRegistry`.
+ * Called from `registerAdminAbilities(registry)` at package level, which
+ * the webapp wires into `initBylineCore()`.
+ */
+export function registerAdminUsersAbilities(registry: AbilityRegistry): void {
+  registry.register({
+    key: ADMIN_USERS_ABILITIES.read,
+    label: 'Read admin users',
+    group: 'admin.users',
+    source: 'admin',
+  })
+  registry.register({
+    key: ADMIN_USERS_ABILITIES.create,
+    label: 'Create admin users',
+    group: 'admin.users',
+    source: 'admin',
+  })
+  registry.register({
+    key: ADMIN_USERS_ABILITIES.update,
+    label: 'Update admin users',
+    group: 'admin.users',
+    source: 'admin',
+  })
+  registry.register({
+    key: ADMIN_USERS_ABILITIES.delete,
+    label: 'Delete admin users',
+    group: 'admin.users',
+    source: 'admin',
+  })
+  registry.register({
+    key: ADMIN_USERS_ABILITIES.changePassword,
+    label: "Change an admin user's password",
+    group: 'admin.users',
+    source: 'admin',
+  })
+}

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

@@ -0,0 +1,157 @@
+/**
+ * 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 './abilities.js'
+import {
+  adminUserListResponseSchema,
+  adminUserResponseSchema,
+  createAdminUserRequestSchema,
+  deleteAdminUserRequestSchema,
+  disableAdminUserRequestSchema,
+  enableAdminUserRequestSchema,
+  getAdminUserRequestSchema,
+  listAdminUsersRequestSchema,
+  okResponseSchema,
+  setAdminUserPasswordRequestSchema,
+  updateAdminUserRequestSchema,
+} from './schemas.js'
+import { AdminUsersService } from './service.js'
+import type { AdminStore } from '../../store.js'
+import type {
+  AdminUserListResponse,
+  AdminUserResponse,
+  CreateAdminUserRequest,
+  DeleteAdminUserRequest,
+  DisableAdminUserRequest,
+  EnableAdminUserRequest,
+  GetAdminUserRequest,
+  ListAdminUsersRequest,
+  OkResponse,
+  SetAdminUserPasswordRequest,
+  UpdateAdminUserRequest,
+} from './schemas.js'
+
+/**
+ * Transport-agnostic commands for the admin-users module.
+ *
+ * Each command is built through `createCommand`, which folds the four
+ * standard steps (Zod-validate input → assert admin actor + ability →
+ * call the service → Zod-validate output) into a single declaration.
+ * The wrapper preserves the historical `(context, input, deps)` call
+ * signature so server fns keep working without change.
+ *
+ * The `deps` argument holds the `AdminStore`. The webapp wraps these in
+ * server fns that supply `deps` from the application's singleton store;
+ * scripts and tests construct their own store and pass it in directly.
+ */
+
+export interface AdminUsersCommandDeps {
+  store: AdminStore
+}
+
+function serviceOf(deps: AdminUsersCommandDeps): AdminUsersService {
+  return new AdminUsersService({ repo: deps.store.adminUsers })
+}
+
+export const listAdminUsersCommand: Command<
+  ListAdminUsersRequest,
+  AdminUserListResponse,
+  AdminUsersCommandDeps
+> = createCommand({
+  method: 'listAdminUsers',
+  auth: { ability: ADMIN_USERS_ABILITIES.read },
+  schemas: { input: listAdminUsersRequestSchema, output: adminUserListResponseSchema },
+  handler: ({ input, deps }) => serviceOf(deps).listUsers(input),
+})
+
+export const getAdminUserCommand: Command<
+  GetAdminUserRequest,
+  AdminUserResponse,
+  AdminUsersCommandDeps
+> = createCommand({
+  method: 'getAdminUser',
+  auth: { ability: ADMIN_USERS_ABILITIES.read },
+  schemas: { input: getAdminUserRequestSchema, output: adminUserResponseSchema },
+  handler: ({ input, deps }) => serviceOf(deps).getUser(input),
+})
+
+export const createAdminUserCommand: Command<
+  CreateAdminUserRequest,
+  AdminUserResponse,
+  AdminUsersCommandDeps
+> = createCommand({
+  method: 'createAdminUser',
+  auth: { ability: ADMIN_USERS_ABILITIES.create },
+  schemas: { input: createAdminUserRequestSchema, output: adminUserResponseSchema },
+  handler: ({ input, deps }) => serviceOf(deps).createUser(input),
+})
+
+export const updateAdminUserCommand: Command<
+  UpdateAdminUserRequest,
+  AdminUserResponse,
+  AdminUsersCommandDeps
+> = createCommand({
+  method: 'updateAdminUser',
+  auth: { ability: ADMIN_USERS_ABILITIES.update },
+  schemas: { input: updateAdminUserRequestSchema, output: adminUserResponseSchema },
+  handler: ({ input, deps }) => serviceOf(deps).updateUser(input),
+})
+
+export const setAdminUserPasswordCommand: Command<
+  SetAdminUserPasswordRequest,
+  AdminUserResponse,
+  AdminUsersCommandDeps
+> = createCommand({
+  method: 'setAdminUserPassword',
+  auth: { ability: ADMIN_USERS_ABILITIES.changePassword },
+  schemas: { input: setAdminUserPasswordRequestSchema, output: adminUserResponseSchema },
+  handler: ({ input, deps }) => serviceOf(deps).setPassword(input),
+})
+
+export const enableAdminUserCommand: Command<
+  EnableAdminUserRequest,
+  OkResponse,
+  AdminUsersCommandDeps
+> = createCommand({
+  method: 'enableAdminUser',
+  auth: { ability: ADMIN_USERS_ABILITIES.update },
+  schemas: { input: enableAdminUserRequestSchema, output: okResponseSchema },
+  handler: async ({ input, deps }) => {
+    await serviceOf(deps).enableUser(input)
+    return { ok: true } as const
+  },
+})
+
+export const disableAdminUserCommand: Command<
+  DisableAdminUserRequest,
+  OkResponse,
+  AdminUsersCommandDeps
+> = createCommand({
+  method: 'disableAdminUser',
+  auth: { ability: ADMIN_USERS_ABILITIES.update },
+  schemas: { input: disableAdminUserRequestSchema, output: okResponseSchema },
+  handler: async ({ input, deps, actor }) => {
+    await serviceOf(deps).disableUser(actor, input)
+    return { ok: true } as const
+  },
+})
+
+export const deleteAdminUserCommand: Command<
+  DeleteAdminUserRequest,
+  OkResponse,
+  AdminUsersCommandDeps
+> = createCommand({
+  method: 'deleteAdminUser',
+  auth: { ability: ADMIN_USERS_ABILITIES.delete },
+  schemas: { input: deleteAdminUserRequestSchema, output: okResponseSchema },
+  handler: async ({ input, deps, actor }) => {
+    await serviceOf(deps).deleteUser(actor, input)
+    return { ok: true } as const
+  },
+})

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

@@ -0,0 +1,63 @@
+/**
+ * CreateAdminUser — drawer form for creating a new admin user.
+ *
+ * Override handles:
+ *   .byline-user-create-wrap     — outer container
+ *   .byline-user-create-form     — vertical-stack form element
+ *   .byline-user-create-grid     — two-column name grid (collapses on mobile)
+ *   .byline-user-create-flags    — checkbox stack (enabled / verified / super)
+ *   .byline-user-create-actions  — Cancel/Save row
+ *   .byline-user-create-action   — buttons in the actions row
+ */
+
+.wrap,
+:global(.byline-user-create-wrap) {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-8);
+  padding: var(--spacing-4);
+  margin-top: var(--spacing-4);
+}
+
+.form,
+:global(.byline-user-create-form) {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-16);
+  padding-top: var(--spacing-8);
+}
+
+.grid,
+:global(.byline-user-create-grid) {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: var(--spacing-16);
+}
+
+@media (min-width: 40rem) {
+  .grid,
+  :global(.byline-user-create-grid) {
+    grid-template-columns: 1fr 1fr;
+  }
+}
+
+.flags,
+:global(.byline-user-create-flags) {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-8);
+}
+
+.actions,
+:global(.byline-user-create-actions) {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--spacing-8);
+  margin-top: var(--spacing-16);
+}
+
+.action,
+:global(.byline-user-create-action) {
+  min-width: 4rem;
+}