@byline/admin 2.3.3 → 2.4.1

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

@@ -0,0 +1,91 @@
+/**
+ * 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-users` — admin user CRUD.
+ *
+ * Exports the adapter-facing `AdminUsersRepository` contract, ability
+ * keys, transport-agnostic commands, the `AdminUsersService`, the seed
+ * helper, and the module's error types. Commands are the recommended
+ * entry point for any caller; the service is exposed for internal uses
+ * (seeds, other services) that want to skip Zod/ability overhead.
+ *
+ * Password hashing is owned by `@byline/admin/auth`; this module takes
+ * pre-hashed `password_hash` strings on the repository boundary so the
+ * adapter never sees plaintext.
+ */
+
+export {
+  ADMIN_USERS_ABILITIES,
+  type AdminUsersAbilityKey,
+  registerAdminUsersAbilities,
+} from './abilities.js'
+export {
+  createAdminUserCommand,
+  deleteAdminUserCommand,
+  disableAdminUserCommand,
+  enableAdminUserCommand,
+  getAdminUserCommand,
+  listAdminUsersCommand,
+  setAdminUserPasswordCommand,
+  updateAdminUserCommand,
+} from './commands.js'
+export { toAdminUser } from './dto.js'
+export {
+  AdminUsersError,
+  type AdminUsersErrorCode,
+  AdminUsersErrorCodes,
+  ERR_ADMIN_USER_EMAIL_IN_USE,
+  ERR_ADMIN_USER_NOT_FOUND,
+  ERR_ADMIN_USER_SELF_DELETE,
+  ERR_ADMIN_USER_SELF_DISABLE,
+  ERR_ADMIN_USER_VERSION_CONFLICT,
+} from './errors.js'
+export {
+  adminUserListResponseSchema,
+  adminUserResponseSchema,
+  createAdminUserRequestSchema,
+  deleteAdminUserRequestSchema,
+  disableAdminUserRequestSchema,
+  enableAdminUserRequestSchema,
+  getAdminUserRequestSchema,
+  listAdminUsersRequestSchema,
+  okResponseSchema,
+  setAdminUserPasswordRequestSchema,
+  updateAdminUserRequestSchema,
+} from './schemas.js'
+export {
+  type SeedSuperAdminInput,
+  type SeedSuperAdminResult,
+  seedSuperAdmin,
+} from './seed-super-admin.js'
+export { AdminUsersService } from './service.js'
+export type { AdminUsersCommandDeps } from './commands.js'
+export type {
+  AdminUserListOrder,
+  AdminUserRow,
+  AdminUsersRepository,
+  AdminUserWithPasswordRow,
+  CountAdminUsersOptions,
+  CreateAdminUserInput,
+  ListAdminUsersOptions,
+  UpdateAdminUserInput,
+} from './repository.js'
+export type {
+  AdminUserListResponse,
+  AdminUserResponse,
+  CreateAdminUserRequest,
+  DeleteAdminUserRequest,
+  DisableAdminUserRequest,
+  EnableAdminUserRequest,
+  GetAdminUserRequest,
+  ListAdminUsersRequest,
+  OkResponse,
+  SetAdminUserPasswordRequest,
+  UpdateAdminUserRequest,
+} from './schemas.js'

package/src/modules/admin-users/repository.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
+ */
+
+/**
+ * `AdminUsersRepository` — the DB-adapter-facing contract for the
+ * `byline_admin_users` table.
+ *
+ * The interface deliberately takes **pre-hashed** password strings
+ * (`password_hash`) rather than plaintext. Argon2 / bcrypt hashing is a
+ * service-layer concern that depends on `@byline/admin/auth` primitives;
+ * keeping it out of the repository means the adapter stays unaware of
+ * password policy and the hashing library of the day.
+ *
+ * **Optimistic concurrency.** Content-shaped writes (`update`,
+ * `setPasswordHash`, `delete`) take an `expectedVid` and bump the stored
+ * `vid` on success. If the stored `vid` does not match `expectedVid` the
+ * adapter throws `AdminUsersError(VERSION_CONFLICT)`, signalling a stale
+ * client. Admin-intent writes that do not depend on current state
+ * (`setEnabled`, login counters) are vid-less — last-writer-wins is the
+ * right semantic for those.
+ *
+ * Adapters (e.g. `@byline/db-postgres`) implement this interface; admin
+ * services (`seed-super-admin`, admin-user commands) consume it. No
+ * caller should ever construct `AdminUsersRepository` instances directly
+ * outside the adapter — use the `AdminStore` bundle passed at
+ * `initBylineCore()` time.
+ */
+
+/**
+ * Public-facing admin-user row — the `password_hash` column is
+ * deliberately omitted. Only `getByEmailForSignIn` returns the hash, and
+ * only so the session provider can verify it.
+ */
+export interface AdminUserRow {
+  id: string
+  vid: number
+  given_name: string | null
+  family_name: string | null
+  username: string | null
+  email: string
+  remember_me: boolean
+  last_login: Date | null
+  last_login_ip: string | null
+  failed_login_attempts: number
+  is_super_admin: boolean
+  is_enabled: boolean
+  is_email_verified: boolean
+  created_at: Date
+  updated_at: Date
+}
+
+/**
+ * Admin-user row including the PHC password hash. Returned only by
+ * `getByEmailForSignIn` — callers must treat it with care (never log,
+ * never return to clients).
+ */
+export interface AdminUserWithPasswordRow extends AdminUserRow {
+  password_hash: string
+}
+
+export interface CreateAdminUserInput {
+  email: string
+  /** Pre-hashed PHC string. Service layer hashes plaintext before calling. */
+  password_hash: string
+  given_name?: string | null
+  family_name?: string | null
+  username?: string | null
+  is_super_admin?: boolean
+  is_enabled?: boolean
+  is_email_verified?: boolean
+}
+
+export interface UpdateAdminUserInput {
+  given_name?: string | null
+  family_name?: string | null
+  username?: string | null
+  email?: string
+  is_super_admin?: boolean
+  is_enabled?: boolean
+  is_email_verified?: boolean
+  remember_me?: boolean
+}
+
+export type AdminUserListOrder =
+  | 'given_name'
+  | 'family_name'
+  | 'email'
+  | 'username'
+  | 'created_at'
+  | 'updated_at'
+
+export interface ListAdminUsersOptions {
+  /** 1-based page number. */
+  page: number
+  /** Page size. Reasonable ceiling applied at the command layer. */
+  pageSize: number
+  /** Free-text search across email, given_name, family_name, username. */
+  query?: string
+  /** Column to sort by. */
+  order: AdminUserListOrder
+  /** True for DESC, false for ASC. */
+  desc: boolean
+}
+
+export interface CountAdminUsersOptions {
+  /** Free-text search — same semantics as `list`. */
+  query?: string
+}
+
+export interface AdminUsersRepository {
+  create(input: CreateAdminUserInput): Promise<AdminUserRow>
+  getById(id: string): Promise<AdminUserRow | null>
+  getByEmail(email: string): Promise<AdminUserRow | null>
+  getByUsername(username: string): Promise<AdminUserRow | null>
+  /**
+   * Sign-in-only lookup. Returns the PHC hash alongside the public row so
+   * the session provider can verify. Callers **must not** persist or echo
+   * the `password_hash` field.
+   */
+  getByEmailForSignIn(email: string): Promise<AdminUserWithPasswordRow | null>
+  /**
+   * Authenticated-verification lookup. Same shape as
+   * `getByEmailForSignIn` but keyed by id — used by the self-service
+   * change-password flow, where the actor is already authenticated and
+   * we need to verify the *current* password before swapping in a new
+   * one. Same handling rules apply: callers **must not** persist or
+   * echo the `password_hash` field.
+   */
+  getByIdForSignIn(id: string): Promise<AdminUserWithPasswordRow | null>
+  /** Paginated, filtered, sorted list. */
+  list(options: ListAdminUsersOptions): Promise<AdminUserRow[]>
+  /** Total row count matching the same filter (for pager `total_pages`). */
+  count(options?: CountAdminUsersOptions): Promise<number>
+  /**
+   * Content update with optimistic concurrency. Throws
+   * `AdminUsersError(VERSION_CONFLICT)` if the stored `vid` differs from
+   * `expectedVid`. Bumps `vid` on success and returns the fresh row.
+   */
+  update(id: string, expectedVid: number, patch: UpdateAdminUserInput): Promise<AdminUserRow>
+  /**
+   * Replace the stored password hash with optimistic concurrency.
+   * Version-gated on `expectedVid`. Caller supplies a pre-hashed PHC string.
+   * Returns the updated row so callers holding the edit form can refresh
+   * their cached `vid` without a second round-trip.
+   */
+  setPasswordHash(id: string, expectedVid: number, passwordHash: string): Promise<AdminUserRow>
+  /** Toggle enabled state. Vid-less — admin intent is independent of other edits. */
+  setEnabled(id: string, enabled: boolean): Promise<void>
+  recordLoginSuccess(id: string, ip: string | null): Promise<void>
+  recordLoginFailure(id: string): Promise<void>
+  /**
+   * Delete with optimistic concurrency. Version-gated on `expectedVid` to
+   * prevent races against a concurrent update.
+   */
+  delete(id: string, expectedVid: number): Promise<void>
+}

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

@@ -0,0 +1,168 @@
+/**
+ * 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 { passwordSchema, uuidSchema } from '@byline/core/validation'
+import { z } from 'zod'
+
+/**
+ * Zod request/response schemas for the admin-users commands.
+ *
+ * Both input and output are validated — response validation keeps the
+ * admin surface honest about what it promises downstream clients. The
+ * DTO shaper in `dto.ts` produces values that match `adminUserResponseSchema`
+ * exactly; if the schema or the DTO drifts, tests catch it at the
+ * command boundary.
+ *
+ * `vid` is the optimistic-concurrency version — every write that touches
+ * content content takes the client-held `vid` and the adapter gates the
+ * write on it, throwing `ADMIN_USER_VERSION_CONFLICT` on mismatch.
+ *
+ * Password and uuid helpers come from `@byline/core/validation` — the
+ * shared primitives ported from the organisation's `@infonomic/shared`
+ * schemas so rules stay consistent across projects.
+ */
+
+// ---------------------------------------------------------------------------
+// Field-level schemas (re-used across requests)
+// ---------------------------------------------------------------------------
+
+const idSchema = uuidSchema
+
+const vidSchema = z
+  .number({ message: 'vid is required' })
+  .int({ message: 'vid must be an integer' })
+  .positive({ message: 'vid must be positive' })
+
+const emailSchema = z
+  .email({ message: 'email must be a valid address' })
+  .min(3)
+  .max(254)
+  .transform((v) => v.toLowerCase())
+
+const nameSchema = z.string().min(1).max(100)
+
+const orderSchema = z.enum([
+  'given_name',
+  'family_name',
+  'email',
+  'username',
+  'created_at',
+  'updated_at',
+])
+
+// ---------------------------------------------------------------------------
+// Requests
+// ---------------------------------------------------------------------------
+
+export const listAdminUsersRequestSchema = z.object({
+  page: z.number().int().min(1).optional().default(1),
+  pageSize: z.number().int().min(1).max(100).optional().default(20),
+  query: z.string().max(128).optional(),
+  order: orderSchema.optional().default('created_at'),
+  desc: z.boolean().optional().default(true),
+})
+export type ListAdminUsersRequest = z.infer<typeof listAdminUsersRequestSchema>
+
+export const getAdminUserRequestSchema = z.object({
+  id: idSchema,
+})
+export type GetAdminUserRequest = z.infer<typeof getAdminUserRequestSchema>
+
+export const createAdminUserRequestSchema = z.object({
+  email: emailSchema,
+  password: passwordSchema,
+  given_name: nameSchema.nullish(),
+  family_name: nameSchema.nullish(),
+  username: z.string().min(1).max(100).nullish(),
+  is_super_admin: z.boolean().optional(),
+  is_enabled: z.boolean().optional(),
+  is_email_verified: z.boolean().optional(),
+})
+export type CreateAdminUserRequest = z.infer<typeof createAdminUserRequestSchema>
+
+export const updateAdminUserRequestSchema = z.object({
+  id: idSchema,
+  vid: vidSchema,
+  patch: z
+    .object({
+      email: emailSchema.optional(),
+      given_name: nameSchema.nullish(),
+      family_name: nameSchema.nullish(),
+      username: z.string().min(1).max(100).nullish(),
+      is_super_admin: z.boolean().optional(),
+      is_enabled: z.boolean().optional(),
+      is_email_verified: z.boolean().optional(),
+    })
+    .refine((p) => Object.keys(p).length > 0, { message: 'patch cannot be empty' }),
+})
+export type UpdateAdminUserRequest = z.infer<typeof updateAdminUserRequestSchema>
+
+export const setAdminUserPasswordRequestSchema = z.object({
+  id: idSchema,
+  vid: vidSchema,
+  password: passwordSchema,
+})
+export type SetAdminUserPasswordRequest = z.infer<typeof setAdminUserPasswordRequestSchema>
+
+export const enableAdminUserRequestSchema = z.object({ id: idSchema })
+export type EnableAdminUserRequest = z.infer<typeof enableAdminUserRequestSchema>
+
+export const disableAdminUserRequestSchema = z.object({ id: idSchema })
+export type DisableAdminUserRequest = z.infer<typeof disableAdminUserRequestSchema>
+
+export const deleteAdminUserRequestSchema = z.object({
+  id: idSchema,
+  vid: vidSchema,
+})
+export type DeleteAdminUserRequest = z.infer<typeof deleteAdminUserRequestSchema>
+
+// ---------------------------------------------------------------------------
+// Responses
+// ---------------------------------------------------------------------------
+
+/**
+ * Public shape of an admin user. Deliberately excludes `password_hash` —
+ * the DTO in `dto.ts` is responsible for producing exactly this shape
+ * from an `AdminUserRow`, so the schema acts as a contract check.
+ */
+export const adminUserResponseSchema = z.object({
+  id: z.string(),
+  vid: z.number().int(),
+  email: z.string(),
+  given_name: z.string().nullable(),
+  family_name: z.string().nullable(),
+  username: z.string().nullable(),
+  remember_me: z.boolean(),
+  last_login: z.date().nullable(),
+  last_login_ip: z.string().nullable(),
+  failed_login_attempts: z.number().int(),
+  is_super_admin: z.boolean(),
+  is_enabled: z.boolean(),
+  is_email_verified: z.boolean(),
+  created_at: z.date(),
+  updated_at: z.date(),
+})
+export type AdminUserResponse = z.infer<typeof adminUserResponseSchema>
+
+export const adminUserListResponseSchema = z.object({
+  users: z.array(adminUserResponseSchema),
+  meta: z.object({
+    total: z.number().int().min(0),
+    total_pages: z.number().int().min(0),
+    page: z.number().int().min(1),
+    page_size: z.number().int().min(1),
+    query: z.string(),
+    order: orderSchema,
+    desc: z.boolean(),
+  }),
+})
+export type AdminUserListResponse = z.infer<typeof adminUserListResponseSchema>
+
+/** Empty response for void-returning mutations (set-password, enable, disable, delete). */
+export const okResponseSchema = z.object({ ok: z.literal(true) })
+export type OkResponse = z.infer<typeof okResponseSchema>

package/src/modules/admin-users/seed-super-admin.ts

@@ -0,0 +1,102 @@
+/**
+ * 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 { hashPassword } from '../auth/password.js'
+import type { AdminStore } from '../../store.js'
+
+export interface SeedSuperAdminInput {
+  email: string
+  /** Plaintext — hashed before insert. */
+  password: string
+  given_name?: string
+  family_name?: string
+  /** Role machine_name. Defaults to `'super-admin'`. */
+  roleMachineName?: string
+  /** Role display name. Defaults to `'Super Admin'`. */
+  roleName?: string
+}
+
+export interface SeedSuperAdminResult {
+  userId: string
+  roleId: string
+  created: {
+    user: boolean
+    role: boolean
+    assignment: boolean
+  }
+}
+
+/**
+ * Idempotently create the super-admin role + user and assign them to each
+ * other. Safe to re-run against an existing database — reports what was
+ * newly created via the `created` flags so scripts can log meaningfully.
+ *
+ * This is the only built-in seed we ship for auth. Everything else is
+ * configured through the admin UI (or directly via the repositories) once
+ * the super-admin is in.
+ *
+ * The user row has `is_super_admin: true` and `is_enabled: true` set
+ * explicitly — the default for `is_enabled` is false so UI-created
+ * accounts require deliberate enablement, but the seed always produces a
+ * usable account.
+ */
+export async function seedSuperAdmin(
+  store: AdminStore,
+  input: SeedSuperAdminInput
+): Promise<SeedSuperAdminResult> {
+  const roleMachineName = input.roleMachineName ?? 'super-admin'
+  const roleName = input.roleName ?? 'Super Admin'
+
+  // 1. Role
+  let role = await store.adminRoles.getByMachineName(roleMachineName)
+  let roleCreated = false
+  if (!role) {
+    role = await store.adminRoles.create({
+      name: roleName,
+      machine_name: roleMachineName,
+      description:
+        'Built-in role held by the initial super-admin. Individual users also carry the is_super_admin flag.',
+      order: 0,
+    })
+    roleCreated = true
+  }
+
+  // 2. User
+  let user = await store.adminUsers.getByEmail(input.email)
+  let userCreated = false
+  if (!user) {
+    const passwordHash = await hashPassword(input.password)
+    user = await store.adminUsers.create({
+      email: input.email,
+      password_hash: passwordHash,
+      given_name: input.given_name ?? null,
+      family_name: input.family_name ?? null,
+      is_super_admin: true,
+      is_enabled: true,
+      is_email_verified: true,
+    })
+    userCreated = true
+  }
+
+  // 3. Assignment (idempotent)
+  const existingRoles = await store.adminRoles.listRolesForUser(user.id)
+  const alreadyAssigned = existingRoles.some((r) => r.id === role.id)
+  if (!alreadyAssigned) {
+    await store.adminRoles.assignToUser(role.id, user.id)
+  }
+
+  return {
+    userId: user.id,
+    roleId: role.id,
+    created: {
+      user: userCreated,
+      role: roleCreated,
+      assignment: !alreadyAssigned,
+    },
+  }
+}

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

@@ -0,0 +1,166 @@
+/**
+ * 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 { AdminAuth } from '@byline/auth'
+
+import { hashPassword } from '../auth/password.js'
+import { toAdminUser } from './dto.js'
+import {
+  ERR_ADMIN_USER_EMAIL_IN_USE,
+  ERR_ADMIN_USER_NOT_FOUND,
+  ERR_ADMIN_USER_SELF_DELETE,
+  ERR_ADMIN_USER_SELF_DISABLE,
+} from './errors.js'
+import type { AdminUsersRepository } from './repository.js'
+import type {
+  AdminUserListResponse,
+  AdminUserResponse,
+  CreateAdminUserRequest,
+  DeleteAdminUserRequest,
+  DisableAdminUserRequest,
+  EnableAdminUserRequest,
+  GetAdminUserRequest,
+  ListAdminUsersRequest,
+  SetAdminUserPasswordRequest,
+  UpdateAdminUserRequest,
+} from './schemas.js'
+
+/**
+ * Business logic for administering admin users.
+ *
+ * The service owns four concerns the repository deliberately avoids:
+ *
+ *   1. **Password hashing.** `hashPassword` from `@byline/admin/auth`
+ *      runs here so every write path (create, setPassword, future
+ *      password-reset flows) hashes consistently.
+ *   2. **Domain invariants.** Email conflict detection on create/update,
+ *      self-delete / self-disable prevention — rules the database
+ *      cannot enforce on its own.
+ *   3. **DTO shaping.** Raw rows are shaped through `toAdminUser` so
+ *      the response contract is owned in one place.
+ *   4. **Optimistic-concurrency plumbing.** The repo gates writes on
+ *      `expectedVid`; the service just threads it from the validated
+ *      request shape. Version conflicts surface as
+ *      `AdminUsersError(VERSION_CONFLICT)` from the adapter; the service
+ *      does not catch them.
+ *
+ * Commands call service methods after Zod-validating input and asserting
+ * abilities; internal callers (seeds, other services) can call service
+ * methods directly. Either way, the service is transport-agnostic.
+ *
+ * Service methods take the acting `AdminAuth` as an explicit first
+ * argument when they need it for invariants (self-delete checks). Reads
+ * do not need the actor — the ability check at the command boundary is
+ * sufficient.
+ */
+export class AdminUsersService {
+  readonly #repo: AdminUsersRepository
+
+  constructor(deps: { repo: AdminUsersRepository }) {
+    this.#repo = deps.repo
+  }
+
+  async listUsers(request: ListAdminUsersRequest): Promise<AdminUserListResponse> {
+    // Run list + count in parallel — they hit the same indexes but
+    // there's no reason to serialise them.
+    const [rows, total] = await Promise.all([
+      this.#repo.list({
+        page: request.page,
+        pageSize: request.pageSize,
+        query: request.query,
+        order: request.order,
+        desc: request.desc,
+      }),
+      this.#repo.count({ query: request.query }),
+    ])
+    const total_pages = Math.max(1, Math.ceil(total / request.pageSize))
+    return {
+      users: rows.map(toAdminUser),
+      meta: {
+        total,
+        total_pages,
+        page: request.page,
+        page_size: request.pageSize,
+        query: request.query ?? '',
+        order: request.order,
+        desc: request.desc,
+      },
+    }
+  }
+
+  async getUser(request: GetAdminUserRequest): Promise<AdminUserResponse> {
+    const row = await this.#repo.getById(request.id)
+    if (!row) throw ERR_ADMIN_USER_NOT_FOUND()
+    return toAdminUser(row)
+  }
+
+  async createUser(request: CreateAdminUserRequest): Promise<AdminUserResponse> {
+    // Pre-check for email conflict. The unique index on `email` is the
+    // ultimate backstop if a race beats this check; the pre-check exists
+    // so the common case returns a clean domain-specific error rather
+    // than a raw Postgres code.
+    const existing = await this.#repo.getByEmail(request.email)
+    if (existing) throw ERR_ADMIN_USER_EMAIL_IN_USE()
+
+    const password_hash = await hashPassword(request.password)
+    const row = await this.#repo.create({
+      email: request.email,
+      password_hash,
+      given_name: request.given_name ?? null,
+      family_name: request.family_name ?? null,
+      username: request.username ?? null,
+      is_super_admin: request.is_super_admin,
+      is_enabled: request.is_enabled,
+      is_email_verified: request.is_email_verified,
+    })
+    return toAdminUser(row)
+  }
+
+  async updateUser(request: UpdateAdminUserRequest): Promise<AdminUserResponse> {
+    const current = await this.#repo.getById(request.id)
+    if (!current) throw ERR_ADMIN_USER_NOT_FOUND()
+
+    // If email is being changed, check that the new address is not taken
+    // by another user.
+    if (request.patch.email != null && request.patch.email !== current.email) {
+      const owner = await this.#repo.getByEmail(request.patch.email)
+      if (owner && owner.id !== request.id) throw ERR_ADMIN_USER_EMAIL_IN_USE()
+    }
+
+    const row = await this.#repo.update(request.id, request.vid, request.patch)
+    return toAdminUser(row)
+  }
+
+  async setPassword(request: SetAdminUserPasswordRequest): Promise<AdminUserResponse> {
+    const exists = await this.#repo.getById(request.id)
+    if (!exists) throw ERR_ADMIN_USER_NOT_FOUND()
+    const password_hash = await hashPassword(request.password)
+    const row = await this.#repo.setPasswordHash(request.id, request.vid, password_hash)
+    return toAdminUser(row)
+  }
+
+  async enableUser(request: EnableAdminUserRequest): Promise<void> {
+    const exists = await this.#repo.getById(request.id)
+    if (!exists) throw ERR_ADMIN_USER_NOT_FOUND()
+    await this.#repo.setEnabled(request.id, true)
+  }
+
+  async disableUser(actor: AdminAuth, request: DisableAdminUserRequest): Promise<void> {
+    if (actor.id === request.id) throw ERR_ADMIN_USER_SELF_DISABLE()
+    const exists = await this.#repo.getById(request.id)
+    if (!exists) throw ERR_ADMIN_USER_NOT_FOUND()
+    await this.#repo.setEnabled(request.id, false)
+  }
+
+  async deleteUser(actor: AdminAuth, request: DeleteAdminUserRequest): Promise<void> {
+    if (actor.id === request.id) throw ERR_ADMIN_USER_SELF_DELETE()
+    const exists = await this.#repo.getById(request.id)
+    if (!exists) throw ERR_ADMIN_USER_NOT_FOUND()
+    await this.#repo.delete(request.id, request.vid)
+  }
+}